Duncan Gibson wrote: >> Author: engelsman >> Date: 2008-10-07 14:07:12 -0700 (Tue, 07 Oct 2008) >> New Revision: 6392 >> Log: >> doxygen comments for undocumented drawing, clipping and color functions >> >> added comments in fl_draw.H, fl_color.cxx and fl_rect.cxx so that the >> links within drawing.dox can be simplified to allow LaTeX/PDF docs too. > > The current drawing.dox provides a function reference/tutorial by using > a lot of function signatures as HTML H4 headers with embedded anchor > names that are linked to from elsewhere. For example, there are full > HTML links to Fl_Widget::draw() that point to the named entry on the > drawing.dox page. > > If we follow the doxygen approach, we would simply remove the full HTML > links, and just leave 'Fl_Widget::draw()' and let doxygen fill in the > details. But then we don't get what we had before. We get a nice link > to the Fl_Widget::draw() method on the Fl_Widget class reference page, > and not into the drawing.dox page. The same will hold true for a lot of > the links within the user manual that currently point in-page rather > than to the class reference. > > How should we proceed? Keep the current in-page links and add explicit > links at the end of the paragraph to Reference Page: Fl_Widget::draw()?
I'm not sure, what exactly to do, but I started changing some links already. My idea was to change the links within the .dox files to doxygen links by using \section and \subsection commands and set links to them by using explicit \ref statements. I wrote something about how to do this in development.dox (short: every (sub)section in one of these files has a name like filename_(sub)section, with (sub)section being unique only in that file). We can then remove the HTML anchor statments. \section will be formatted like H2, \subsection like H3 (\page like H1). If we use the class or function name directly, e.g. 'Fl_Widget::draw()', then we will get a link to the class or function reference. The only problem would be to decide, *what* we want at any given point in the docs. IMHO, we should use doxygen links to class names and use the doxygen features everywhere in the source and header files, as if we wouldn't have the tutorial chapters (unless someone wants to link to the tutorial chapter explicitly). But we should change the links to (sub)section links *within* the tutorial chapters. I.e. remove all (or most) explicit html links from the source and header files and use \ref statements only to reference to the tutorial chapters, if really intended at that point. Would this work for the LaTeX docs? FWIW: Here is an example from drawing.dox, how we can have both: <A NAME="colors"></A> <!-- For old HTML links only ! --> \section drawing_colors Colors I did this only, because there might have been old links that I didn't find, but the first (HTML anchor) line could be removed, if we are sure that there are no more old html links. But I wouldn't like to do this double work for much more links, i.e. if we decide to remove all old html references to the html anchor statements, then I could go on changing the links/sections/subsections within the tutorial .dox files. Albrecht _______________________________________________ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
