FLTK PDF docs generation with doxygen > 1.8.6

[Albrecht Schlosser]

Hi all (devs and others)

I was wondering why I could not generate the PDF documentation with my
Ubuntu 16.04 LTS, but I never found the time (or it didn't seem
important enough) to investigate further. The error messages I found
were LaTeX specific and seemed very cryptic to me - at least I didn't
find a way to "fix" anything.

For tests I went "back in time" and used my older Ubuntu 14.04 LTS. Now
I compiled a newer doxygen version (on that system) to get an up-to-date
documentation, but I had to realize that all doxygen versions since
1.8.7 were "broken" in a way that I could not generate the FLTK PDF
docs, i.e. with all versions from 1.8.7 to 1.8.14 (current git version).

Note that the (FLTK) HTML docs generation doesn't have issues.

I can also generate doxygen's own PDF documentation with newer doxygen
versions.

What are your experiences?

Which doxygen versions do you use to generate the FLTK PDF docs
(successfully)?

If you can do it with doxygen > 1.8.6:

(a) which OS version?
(b) which LaTeX specific and other packages did you install?

Further information:

After downgrading to a self-built doxygen 1.8.6 I can successfully build
the FLTK PDF docs on all my Ubuntu versions (14.04, 16.04, 18.04).

Building doxygen 1.8.6 needs autoconf/configure and doesn't work OOTB
because the newer systems (16.04 and 18.04) use flex 2.6.0 and 2.6.4,
resp., but the old (1.8.6) doxygen source compares flex versions
internally in a way that only flex 2.5.x is accepted. I have a patch for
doxygen 1.8.6 available, in case someone is interested.

Doxygen sources:

https://github.com/doxygen/doxygen

Later versions of doxygen (IIRC 1.8.11++) use CMake for building doxygen
and the "bug" in 1.8.6 appears to be fixed (but I couldn't use them to
generate FLTK's PDF docs).

According to doxygen's own build process I tried to build with the
following packages (besides the obvious ones):

- texlive
- texlive-extra-utils
- texlive-latex-extra

but my build also required 'epstopdf' so I had to install:

- texlive-font-utils

Before I open a doxygen issue I'd like to read about your experiences,
solutions, or proposals.

Maybe someone more savvy regarding LaTeX can interpret the error
messages (built with cmake + ninja):

$ ninja pdf
[1/1] Generating PDF documentation
FAILED: documentation/fltk.pdf
cd /home/albrecht/git/fltk-1.4/build/all_warnings/documentation &&
/usr/bin/doxygen Doxybook &&
/home/albrecht/git/fltk-1.4/documentation/make_pdf && cp -f
latex/refman.pdf fltk.pdf
cp: cannot stat 'latex/refman.pdf': No such file or directory
ninja: build stopped: subcommand failed.

$ tail documentation/pdfall.log
! Undefined control sequence.
l.174 ...+G\+HT H\+O\+L\+D\+E\+RS A\+N\+D/\+OR O\+
T\+H\+ER
P\+A\+R\+T\+I\+ES...

! Undefined control sequence.
l.174 ...+HT H\+O\+L\+D\+E\+RS A\+N\+D/\+OR O\+T\+
H\+ER
P\+A\+R\+T\+I\+ES P\...
(That makes 100 errors; please try again.)
! ==> Fatal error occurred, no output PDF file produced!
Transcript written on refman.log.

[end of build and error messages]

FWIW: I tried to remove our special latex header (fltk-book.tex.in) by
editing Doxyfile.in:

LATEX_HEADER =

(no LATEX_HEADER), but with no success.

All comments appreciated!

[Greg Ercolano]

On 08/04/18 06:10, Albrecht Schlosser wrote:
> Later versions of doxygen (IIRC 1.8.11++) use CMake for building doxygen
> and the "bug" in 1.8.6 appears to be fixed (but I couldn't use them to
> generate FLTK's PDF docs).
>
> According to doxygen's own build process I tried to build with the
> following packages (besides the obvious ones):
>
> - texlive
> - texlive-extra-utils
> - texlive-latex-extra
>
> but my build also required 'epstopdf' so I had to install:
>
> - texlive-font-utils

On Sci Linux 7.x I found I needed to add this one extra package
to get the PDF to build:

yum install texlive-epstopdf

Here I'm using the default doxygen/latex that came with the OS
default workstation installation with the development stuff installed.
Regarding version#s, FWIW:

[erco@harris] 3417 # doxygen -v
1.8.15
^^^^^^

[erco@harris] 3421 # latex -v
pdfTeX 3.1415926-2.5-1.40.14 (TeX Live 2013)
^^^^^^^^^ LOL
kpathsea version 6.1.1
Copyright 2013 Peter Breitenlohner (eTeX)/Han The Thanh (pdfTeX).
There is NO warranty. Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Peter Breitenlohner (eTeX)/Han The Thanh (pdfTeX).
Compiled with libpng 1.5.13; using libpng 1.5.13
Compiled with zlib 1.2.7; using zlib 1.2.7
Compiled with poppler version 0.26.5

I, like you, received some obscure errors from LaTeX,
and had to wade through a bunch of articles on the net
before finding that missing piece.

[Albrecht Schlosser]

On 04.08.2018 18:33 Greg Ercolano wrote:
> On 08/04/18 06:10, Albrecht Schlosser wrote:
>> Later versions of doxygen (IIRC 1.8.11++) use CMake for building doxygen
>> and the "bug" in 1.8.6 appears to be fixed (but I couldn't use them to
>> generate FLTK's PDF docs).
>>
>> According to doxygen's own build process I tried to build with the
>> following packages (besides the obvious ones):
>>
>> - texlive
>> - texlive-extra-utils
>> - texlive-latex-extra
>>
>> but my build also required 'epstopdf' so I had to install:
>>
>> - texlive-font-utils
>
> On Sci Linux 7.x I found I needed to add this one extra package
> to get the PDF to build:
>
> yum install texlive-epstopdf
>
> Here I'm using the default doxygen/latex that came with the OS
> default workstation installation with the development stuff installed.
> Regarding version#s, FWIW:
>
> [erco@harris] 3417 # doxygen -v
> 1.8.15
> ^^^^^^

Wow, that's really bleeding edge. The latest official release is 1.8.14.
Ubuntu 18.04 LTS has 1.8.13, but I also tried 1.8.14 and git master (aka
1.8.15) w/o success.

> [erco@harris] 3421 # latex -v
> pdfTeX 3.1415926-2.5-1.40.14 (TeX Live 2013)
> ^^^^^^^^^ LOL
> kpathsea version 6.1.1
> Copyright 2013 Peter Breitenlohner (eTeX)/Han The Thanh (pdfTeX).
> There is NO warranty. Redistribution of this software is
> covered by the terms of both the pdfTeX copyright and
> the Lesser GNU General Public License.
> For more information about these matters, see the file
> named COPYING and the pdfTeX source.
> Primary author of pdfTeX: Peter Breitenlohner (eTeX)/Han The Thanh (pdfTeX).
> Compiled with libpng 1.5.13; using libpng 1.5.13
> Compiled with zlib 1.2.7; using zlib 1.2.7
> Compiled with poppler version 0.26.5

This appears to be older than my version on Ubuntu 18.04:

$ latex --version
pdfTeX 3.14159265-2.6-1.40.18 (TeX Live 2017/Debian)
kpathsea version 6.2.3
Copyright 2017 Han The Thanh (pdfTeX) et al.

There is NO warranty. Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the pdfTeX source.

Primary author of pdfTeX: Han The Thanh (pdfTeX) et al.
Compiled with libpng 1.6.34; using libpng 1.6.34
Compiled with zlib 1.2.11; using zlib 1.2.11
Compiled with poppler version 0.62.0

> I, like you, received some obscure errors from LaTeX,
> and had to wade through a bunch of articles on the net
> before finding that missing piece.

Well, the missing package was easy to find. I got an explicit error
message that epstopdf was missing, and running `epstopdf` revealed the
package name I had to install (texlive-font-utils). This is a nice
feature of Ubuntu (no need to search packages).

But I still can't generate the FLTK 1.4 PDF docs, and very likely
neither 1.3 PDF docs. I should try the latter tomorrow.

Does it really work for you in this setup?

[Greg Ercolano]

On 08/04/18 18:42, Albrecht Schlosser wrote:
> On 04.08.2018 18:33 Greg Ercolano wrote:
>> [erco@harris] 3417 # doxygen -v
>> 1.8.15
>> ^^^^^^
>
> Wow, that's really bleeding edge. The latest official release is 1.8.14.

Oh right, yeah, I pulled the latest doxygen thinking it would solve
that problem and it didn't. (But continued to use it anyway for doing
the HTML, as there were some nice new features in the generated HTML)

I forgot I gave up and went back to my older system's PDF generator,
and thought screw it, the HTML docs are easier to read, so I didn't
think it worth pursuing.

The problem was deeper in the LaTeX stuff (see the make_pdf script)
which barfed about missing .sty files (a4wide.sty, tabu, adjustbox, etc)
that I could never find, and latex is so massive and has so many
dependencies (that whole texlive thing is incredibly huge), it seemed
pretty hopeless.

[Albrecht Schlosser]

On 05.08.2018 05:42 Greg Ercolano wrote:
> On 08/04/18 18:42, Albrecht Schlosser wrote:
>> On 04.08.2018 18:33 Greg Ercolano wrote:
>>> [erco@harris] 3417 # doxygen -v
>>> 1.8.15
>>> ^^^^^^
>>
>> Wow, that's really bleeding edge. The latest official release is 1.8.14.
>
> Oh right, yeah, I pulled the latest doxygen thinking it would solve
> that problem and it didn't. (But continued to use it anyway for doing
> the HTML, as there were some nice new features in the generated HTML)

I didn't really compare the HTML output but I wanted to be up-to-date
anyway, particularly because I intend to release 1.3.5 soon, if devs
agree. Since we also release documentation tarballs I wanted to be prepared.

> I forgot I gave up and went back to my older system's PDF generator,
> and thought screw it, the HTML docs are easier to read, so I didn't
> think it worth pursuing.

Same here, but now things have changed...

> The problem was deeper in the LaTeX stuff (see the make_pdf script)
> which barfed about missing .sty files (a4wide.sty, tabu, adjustbox, etc)
> that I could never find, and latex is so massive and has so many
> dependencies (that whole texlive thing is incredibly huge), it seemed
> pretty hopeless.

Yes, that's what I had thought as well. It is even worse since the LaTeX
code is *generated* by doxygen and I have no clue what is correct and
what would be faulty LaTeX code.

The good news are: after a really long night testing (until ~ 5 am) I
found that the culprit was our fltk-book.tex file. This file can be
generated by doxygen and then modified to fit our needs. Unfortunately
our file was really outdated and broke the PDF generation. The new file
I generated was usable in my tests with doxygen 1.8.6 and 1.8.13 and
1.8.15 (git). Other versions not yet tested. Do we need more/older versions?

FYI:

$ doxygen -w html ... generates HTML and CSS stuff
$ doxygen -w latex ... generates LaTeX headers, footer etc.

See `man doxygen'.

The bad news: after generating a new fltk-book.tex[.in] file I could
generate pdf docs for *almost* everything. Doxygen 1.8.6 works well and
can generate the whole PDF file, but 1.8.13 still aborts pdf generation.

Many tries later I found that only classes Fl_Input and Fl_Tree had
issues :-( , but everything else works now. :-)
So far so good.

I pushed a commit to our GitHub test repository to save what I have
found out so far in branch doxygen_pdf for myself and for early testers.
( Hint! ;-) )

To get it, check out the fltk-test.git repository from GitHub and switch
to branch doxygen_pdf, like this:

$ git clone https://github.com/fltk/fltk-test.git [optional subdir]

Defaults to subdirectory fltk-test:

$ cd fltk-test
$ git checkout doxygen_pdf

Build and generate pdf docs...

Test results and comments would be appreciated.

I'll go ahead and try to find out why Fl_Input and Fl_Tree break the pdf
generation.

[Greg Ercolano]

On 08/05/18 10:58, Albrecht Schlosser wrote:
> Yes, that's what I had thought as well. It is even worse since the LaTeX
> code is *generated* by doxygen and I have no clue what is correct and
> what would be faulty LaTeX code.

From what I could tell, the big issue seemed to be doxygen genereated
tex files were referring to either "obsolete" or missing external
"style files (.sty)

> The good news are: after a really long night testing (until ~ 5 am) I
> found that the culprit was our fltk-book.tex file. This file can be
> generated by doxygen and then modified to fit our needs. Unfortunately
> our file was really outdated and broke the PDF generation. The new file
> I generated was usable in my tests with doxygen 1.8.6 and 1.8.13 and
> 1.8.15 (git). Other versions not yet tested. Do we need more/older versions?

Sounds like we should test the latex version in our Makefile,
and sed the data accordingly.

> $ doxygen -w html ... generates HTML and CSS stuff
> $ doxygen -w latex ... generates LaTeX headers, footer etc.
>
> See `man doxygen'.

Ya, I saw those -- see also 'doxygen -help' which shows the
same stuff.

Both the man page and the help docs are only about a page long,
barely useful.

They neglect to mention (for the latex and rtf output) that you
need specific flags in the Doxyfile for those to work at all, or
it will silently do nothing.

For instance with our defaults:

make Doxyfile ; doxygen -w rtf

..does nothing unless the *RTF* macros in the Doxyfile are
enabled. The manpage, -help, and even the website docs don't
elaborate.. you're supposed to be familiar with the Doxyfile
to know about those settings.

> The bad news: after generating a new fltk-book.tex[.in] file I could
> generate pdf docs for *almost* everything. Doxygen 1.8.6 works well and
> can generate the whole PDF file, but 1.8.13 still aborts pdf generation.
>
> Many tries later I found that only classes Fl_Input and Fl_Tree had
> issues :-( , but everything else works now. :-)
> So far so good.

Sounds good..

> I pushed a commit to our GitHub test repository to save what I have
> found out so far in branch doxygen_pdf for myself and for early testers.
> ( Hint! ;-) )

OK, I'll try checking out that branch.

> To get it, check out the fltk-test.git repository from GitHub and switch
> to branch doxygen_pdf, like this:
>
> $ git clone https://github.com/fltk/fltk-test.git [optional subdir]
>
> Defaults to subdirectory fltk-test:
>
> $ cd fltk-test
> $ git checkout doxygen_pdf
>
> Build and generate pdf docs...
>
> Test results and comments would be appreciated.
>
> I'll go ahead and try to find out why Fl_Input and Fl_Tree break the pdf
> generation.

Done.

Hmm, still getting an error:

---
$ make pdf
Generating Doxybook ...
Generating PDF documentation ...
/usr/local/src/fltk-1.4.x-git/src/Fl_File_Chooser2.cxx:190: warning: no uniquely matching class member found for
void Fl_File_Chooser::filter(char< em > pattern)
Possible candidates:
void Fl_File_Chooser::filter(const char *p)' at line 137 of file /usr/local/src/fltk-1.4.x-git/FL/Fl_File_Chooser.H
const char * Fl_File_Chooser::filter()' at line 138 of file /usr/local/src/fltk-1.4.x-git/FL/Fl_File_Chooser.H

/usr/local/src/fltk-1.4.x-git/documentation/src/development.dox:149: warning: Invalid section id `development_non'; ignoring section

cp: cannot stat 'latex/refman.pdf': No such file or directory

make: *** [pdf] Error 1
---

That last bit means 'it didn't work'.
Looking at the pdfall.log (generated by our make_pdf script), it says:

---
$ cat pdfall.log
This is pdfTeX, Version 3.1415926-2.5-1.40.14 (TeX Live 2013)
restricted \write18 enabled.
entering extended mode
(./refman.tex
LaTeX2e <2011/06/27>
Babel <v3.8m> and hyphenation patterns for english, dumylang, nohyphenation, loaded.

Input index file refman.idx not found. <--
Usage: makeindex [-ilqrcgLT] [-s sty] [-o ind] [-t log] [-p num] [idx0 idx1 ...] <--
This is pdfTeX, Version 3.1415926-2.5-1.40.14 (TeX Live 2013) <--
restricted \write18 enabled.
entering extended mode
(./refman.tex
LaTeX2e <2011/06/27>
Babel <v3.8m> and hyphenation patterns for english, dumylang, nohyphenation, loaded.
---

[Greg Ercolano]

On 08/05/18 11:23, Greg Ercolano wrote:
>> I pushed a commit to our GitHub test repository to save what I have
>> found out so far in branch doxygen_pdf for myself and for early testers.
>> ( Hint! ;-)

>>>> Test results and comments would be appreciated.

> Hmm, still getting an error:
>
> ---
> $ make pdf
> Generating Doxybook ...
> Generating PDF documentation ...

> [..]

> cp: cannot stat 'latex/refman.pdf': No such file or directory
> make: *** [pdf] Error 1
> ---
>
> That last bit means 'it didn't work'.
> Looking at the pdfall.log (generated by our make_pdf script), it says:
>
> ---
> $ cat pdfall.log

> [..]

> Input index file refman.idx not found. <--
> Usage: makeindex [-ilqrcgLT] [-s sty] [-o ind] [-t log] [-p num] [idx0 idx1 ...] <--

Hmm, seems like the latex/refman.log file has the usual "can't find .sty" error:

! LaTeX Error: File `tabu.sty' not found.

To solve that, and similar errors, I found that I could just touch(1)
the missing file, and re-running:

pdflatex --interaction=nonstopmode refman.tex

..checking the refman.log file each pass for .sty errors it couldn't find,
and rinse/repeat until it finally generated a refman.pdf file.

I had to touch these .sty files to get it to fly:

touch tabu.sty hanging.sty adjustbox.sty stackengine.sty sectsty.sty tocloft.sty
pdflatex --interaction=nonstopmode refman.tex

There were still a lot of "Error" messages in the refman.log, but at least
it created a pdf, which is around 4.4MB.

It'd definitely incomplete though; there's no index, and there's several
areas that are black with text inside.

[Albrecht Schlosser]

On 05.08.2018 20:23 Greg Ercolano wrote:
> On 08/05/18 10:58, Albrecht Schlosser wrote:
>> Yes, that's what I had thought as well. It is even worse since the LaTeX
>> code is *generated* by doxygen and I have no clue what is correct and
>> what would be faulty LaTeX code.
>
> From what I could tell, the big issue seemed to be doxygen genereated
> tex files were referring to either "obsolete" or missing external
> "style files (.sty)

I know I had such issues (missing .sty files) as well, and I struggled
hard to get the right packages installed on my previous (Ubuntu 14.04)
system. From an old log I see that I installed all these packages w/o
success:

texlive-latex-base
texlive-latex-extra
texlive-latex-recommended
texlive-bibtex-extra
texlive-fonts-extra
texlive-extra-utils
texlive-font-utils
fonts-freefont
texlive-formats-extra
psutils

.. until I installed:

texlive-full

... which is very large. I logged that the download took 30 min. but
that was with a 6 MBit or slower internet connection.

Now I found doxygen's .travis.yml file with these instructions for
doxygen's own documentation (CI) builds:

install:
- sudo apt-get install -qq texlive
- sudo apt-get install -qq texlive-extra-utils
- sudo apt-get install -q -y texlive-latex-extra

Hence I used these packages on a fresh Ubuntu 18.04 and it worked
/basically/, I only had to install 'epstopdf' which can be installed by
Ubuntu package `texlive-font-utils' as I wrote in my initial post.

Maybe you can try to replicate this setup with your SciLinux?

However, I don't know the corresponding package names, and older or
newer package versions might not be compatible. I don't know.

>> The good news are: after a really long night testing (until ~ 5 am) I
>> found that the culprit was our fltk-book.tex file. This file can be
>> generated by doxygen and then modified to fit our needs. Unfortunately
>> our file was really outdated and broke the PDF generation. The new file
>> I generated was usable in my tests with doxygen 1.8.6 and 1.8.13 and
>> 1.8.15 (git). Other versions not yet tested. Do we need more/older versions?
>
> Sounds like we should test the latex version in our Makefile,
> and sed the data accordingly.

AFAICT the new LaTeX header file is compatible with a wide range (1.8.6
- 1.8.15) so I hope this is not necessary. Otherwise we'd have to use
two different 'fltk-book.tex.in' files, maybe.

>> $ doxygen -w html ... generates HTML and CSS stuff
>> $ doxygen -w latex ... generates LaTeX headers, footer etc.
>>
>> See `man doxygen'.
>
> Ya, I saw those -- see also 'doxygen -help' which shows the
> same stuff.
>
> Both the man page and the help docs are only about a page long,
> barely useful.
>
> They neglect to mention (for the latex and rtf output) that you
> need specific flags in the Doxyfile for those to work at all, or
> it will silently do nothing.

I remembered that I had to do the same for the html/css stuff and I did
it now for the latex stuff and it just worked. The config file (last
argument) is optional, but maybe you always need one - it might default
to Doxyfile - I don't know. It worked for me...

>> Many tries later I found that only classes Fl_Input and Fl_Tree had
>> issues :-( , but everything else works now. :-)
>> So far so good.
>
> Sounds good..

... but I will need more time (maybe tomorrow) to investigate further,
and I don't know if I have a chance to succeed. We'll see.

>> I pushed a commit to our GitHub test repository to save what I have
>> found out so far in branch doxygen_pdf for myself and for early testers.
>> ( Hint! ;-) )
>
> OK, I'll try checking out that branch.

> ...

> Hmm, still getting an error:
>
> ---
> $ make pdf
> Generating Doxybook ...
> Generating PDF documentation ...
> /usr/local/src/fltk-1.4.x-git/src/Fl_File_Chooser2.cxx:190: warning: no uniquely matching class member found for
> void Fl_File_Chooser::filter(char< em > pattern)
> Possible candidates:
> void Fl_File_Chooser::filter(const char *p)' at line 137 of file /usr/local/src/fltk-1.4.x-git/FL/Fl_File_Chooser.H
> const char * Fl_File_Chooser::filter()' at line 138 of file /usr/local/src/fltk-1.4.x-git/FL/Fl_File_Chooser.H
>
> /usr/local/src/fltk-1.4.x-git/documentation/src/development.dox:149: warning: Invalid section id `development_non'; ignoring section
> cp: cannot stat 'latex/refman.pdf': No such file or directory
> make: *** [pdf] Error 1
> ---
>
> That last bit means 'it didn't work'.

Did you clean the build and start over?

I remember that I once saw exactly this/these error message(s) but I
don't remember that I "fixed" it somehow. I supposedly started a new
build to be sure, and that seemed to work.

With the current setup in the mentioned branch I don't get any warnings
or error messages.

[Albrecht Schlosser]

On 05.08.2018 20:40 Greg Ercolano wrote:
> On 08/05/18 11:23, Greg Ercolano wrote:
>>> I pushed a commit to our GitHub test repository to save what I have
>>> found out so far in branch doxygen_pdf for myself and for early testers.
>>> ( Hint! ;-)
>>>>> Test results and comments would be appreciated.
>
>> Hmm, still getting an error:
>>
>> ---
>> $ make pdf
>> Generating Doxybook ...
>> Generating PDF documentation ...
>> [..]
>> cp: cannot stat 'latex/refman.pdf': No such file or directory
>> make: *** [pdf] Error 1
>> ---
>>
>> That last bit means 'it didn't work'.
>> Looking at the pdfall.log (generated by our make_pdf script), it says:

Yes, that's what I also used. I studied our Makefile and the one created
by doxygen (?) in the 'latex' build directory. It was helpful to use the
latter directly: cd latex; make. I also added some 'echo' statements...

>> $ cat pdfall.log
>> [..]
>> Input index file refman.idx not found. <--
>> Usage: makeindex [-ilqrcgLT] [-s sty] [-o ind] [-t log] [-p num] [idx0 idx1 ...] <--

I believe this part is benign. PDF generation with index is an iterative
process.

> Hmm, seems like the latex/refman.log file has the usual "can't find .sty" error:
>
> ! LaTeX Error: File `tabu.sty' not found.
>
> To solve that, and similar errors, I found that I could just touch(1)
> the missing file, and re-running:
>
> pdflatex --interaction=nonstopmode refman.tex
>
> ..checking the refman.log file each pass for .sty errors it couldn't find,
> and rinse/repeat until it finally generated a refman.pdf file.
>
> I had to touch these .sty files to get it to fly:
>
> touch tabu.sty hanging.sty adjustbox.sty stackengine.sty sectsty.sty tocloft.sty
> pdflatex --interaction=nonstopmode refman.tex

I would likely have done the same to get forward but that's only a
workaround and not a solution. I'd rather try to "find" the latex
packages/modules in your distro's latex installation packages.

> There were still a lot of "Error" messages in the refman.log, but at least
> it created a pdf, which is around 4.4MB.
>
> It'd definitely incomplete though; there's no index, and there's several
> areas that are black with text inside.

Mine is now about 5 MB (as it used to be) with 1363 pages and seems to
be complete except the missing two classes (and those derived from those).

[Greg Ercolano]

On 08/05/18 13:22, Albrecht Schlosser wrote:
> .. until I installed:
>
> texlive-full

Ya, I don't have that.. wish I did.

Certainly the master texlive package was installed.

The 'yum search texlive' is a huge list; 690 packages (ugh).

I'm now trying something extreme; taking that list of texlive* packages
and doing a 'repoquery -l' on each one to get a master list of all files
each package provides.

---
#!/bin/csh -f
#
# Get all filenames provided by all texlive* packages into /tmp/everything.out
#
sleep 0 > /tmp/everything.out
foreach i ( `yum search texlive | grep ^texlive | cut -d: -f1` )
echo Working on $i
repoquery -l $i | awk '{ printf("'$i': %s\n",$0); }' >> /tmp/everything.out
end
---
..then grepping for those missing .sty files to find which packages I need..
unfortunately I could only find 3 files of the 6 needed:

$ egrep 'tabu.sty|hanging.sty|adjustbox.sty|stackengine.sty|sectsty.sty|tocloft.sty' /tmp/everything.out
texlive-adjustbox.noarch: /usr/share/texlive/texmf-dist/tex/latex/adjustbox/adjustbox.sty
texlive-sectsty.noarch: /usr/share/texlive/texmf-dist/tex/latex/sectsty/sectsty.sty
texlive-tocloft.noarch: /usr/share/texlive/texmf-dist/tex/latex/tocloft/tocloft.sty

So on the left is the package name, and on the right the absolute path
for the file if the package were installed.

Installing those 3 matching packages, and doing 'make pdf'.. still failed,
*but* when I touch(1)ed the other missing files to get it to work, I was able
to get a *much nicer* PDF with an index. There were many errors in the refman.log,
but the pdflatex ran to completion at least.

So this series of commands "worked" for me, with only 3 files needing to be hacked:

cd documentation
make clean Doxyfile Doxybook src/fltk-book.tex
doxygen Doxybook
cd latex
touch tabu.sty hanging.sty stackengine.sty # <-- HACK
pdflatex refman.tex
makeindex refman.idx
pdflatex refman.tex

With that, 'makeindex' didn't fail, and it built a much larger PDF
than my first hack attempt (1366 pages instead of 1253).

The PDF looks pretty good; it has an index sidebar, a large index at
the head of the document (that takes up the first 106 pages).

But I still see large black areas on some pages which appear to be the
first description page of some methods (probably caused by my touch hackery?)
and the 'doxygen Doxybook' still throws an error about Fl_File_Chooser2.cxx.
I dropped the resulting PDF file here:

http://seriss.com/people/erco/tmp/refman-1.4.x-git--branch--doxygen_pdf.pdf

The first 'black area' appears on page 359/1366. There's text inside of it,
but it's hard to see because of black text on black. (sigh)

[Albrecht Schlosser]

On 05.08.2018 22:34 Albrecht Schlosser wrote:

> Mine is now about 5 MB (as it used to be) with 1363 pages and seems to
> be complete except the missing two classes (and those derived from those).

Now PDF (and HTML) docs are complete again! :-)

See this commit at GitHub:
<https://github.com/fltk/fltk-test/commit/d977df0f0f149bd3cf4f47cd2a10e1ef86eb15c9>

and the latest commit fixing the "revision number".
<https://github.com/fltk/fltk-test/commit/81ec5023bea3a8a058e426ba82c5f6c440f8bbcc>

HTML docs are online:

https://fltk.gitlab.io/fltk-test/
https://fltk.gitlab.io/fltk-test/classFl__Input.html
https://fltk.gitlab.io/fltk-test/classFl__Tree.html

Please check the effects of commenting the <CAPTION> tag out,
particularly in class Fl_Tree, but also in Fl_Input. TIA.

[Albrecht Schlosser]

On 06.08.2018 01:23 Albrecht Schlosser wrote:
> On 05.08.2018 22:34 Albrecht Schlosser wrote:
>
>> Mine is now about 5 MB (as it used to be) with 1363 pages and seems to
>> be complete except the missing two classes (and those derived from
>> those).
>
> Now PDF (and HTML) docs are complete again! :-)
>
> See this commit at GitHub:
> <https://github.com/fltk/fltk-test/commit/d977df0f0f149bd3cf4f47cd2a10e1ef86eb15c9>

BTW: It's frustrating to see how much time I *wasted* to find the
culprit(s) of both issues:

(1) the outdated latex header

(2) the <CAPTION> statement in the two FLTK header files

There were no helping error messages. For the 2nd issue there were
basically *NO* error messages at all except something like "A fatal
error has occurred" or similar.

I found the offending files by trial and error (modifying the list of
processed files, kinda binary search, every time up to 60 seconds
processing until the error showed up).

Then I needed to find the offending <CAPTION> statement. I couldn't find
anything obvious in the code, so I had to use trial and error again by
adding '#ifndef FL_DOXYGEN' to exclude parts of the file from doxygen
processing (again I used "binary search"), until I found the <CAPTION>
statement to be the cause in Fl_Tree.H. The next step was quick: `git
grep CAPTION' showed the other two occurrences in Fl_Input.H.

I have no idea why doxygen 1.8.6 was "immune". Maybe it ignored the
offending statement. I can add that there were no warnings at the
doxygen processing stage.

[Albrecht Schlosser]

On 06.08.2018 01:04 Greg Ercolano wrote:
>
> I'm now trying something extreme; taking that list of texlive* packages
> and doing a 'repoquery -l' on each one to get a master list of all files
> each package provides.

> ...

> Installing those 3 matching packages, and doing 'make pdf'.. still failed,
> *but* when I touch(1)ed the other missing files to get it to work, I was able
> to get a *much nicer* PDF with an index. There were many errors in the refman.log,
> but the pdflatex ran to completion at least.
>
> So this series of commands "worked" for me, with only 3 files needing to be hacked:
>
> cd documentation
> make clean Doxyfile Doxybook src/fltk-book.tex
> doxygen Doxybook
> cd latex
> touch tabu.sty hanging.sty stackengine.sty # <-- HACK
> pdflatex refman.tex
> makeindex refman.idx
> pdflatex refman.tex
>
> With that, 'makeindex' didn't fail, and it built a much larger PDF
> than my first hack attempt (1366 pages instead of 1253).
>
> The PDF looks pretty good; it has an index sidebar, a large index at
> the head of the document (that takes up the first 106 pages).

You might need to repeat the `makeindex;pdflatex' steps a few more
times. After my experience I guess you could also have run `make' in the
latex directory after you 'touch'ed the missing files. This should do
the magic.

Maybe this can help:

$ for f in hanging.sty tabu.sty stackengine.sty;do apt-file find $f;done
texlive-latex-extra:
/usr/share/texlive/texmf-dist/tex/latex/hanging/hanging.sty
texlive-latex-recommended:
/usr/share/texlive/texmf-dist/tex/latex/lwarp/lwarp-hanging.sty
texlive-xetex:
/usr/share/texlive/texmf-dist/tex/xetex/xetexko/xetexko-hanging.sty
texlive-latex-extra: /usr/share/texlive/texmf-dist/tex/latex/tabu/tabu.sty
texlive-latex-extra:
/usr/share/texlive/texmf-dist/tex/latex/stackengine/stackengine.sty
texlive-latex-extra:
/usr/share/texlive/texmf-dist/tex/latex/tabstackengine/tabstackengine.sty

You can see the package name and the installation path.

> But I still see large black areas on some pages which appear to be the
> first description page of some methods (probably caused by my touch hackery?)
> and the 'doxygen Doxybook' still throws an error about Fl_File_Chooser2.cxx.
> I dropped the resulting PDF file here:
>
> http://seriss.com/people/erco/tmp/refman-1.4.x-git--branch--doxygen_pdf.pdf

I took a quick look at it. Black is beautiful ;-)

If you really want to see content you can mark/select it and (if that is
not enough to reveal the text) copy and paste it elsewhere.

[Albrecht Schlosser]

On 06.08.2018 02:05 Albrecht Schlosser wrote:
>
> Maybe this can help:
>
> $ for f in hanging.sty tabu.sty stackengine.sty;do apt-file find $f;done
> texlive-latex-extra:
> /usr/share/texlive/texmf-dist/tex/latex/hanging/hanging.sty
> texlive-latex-recommended:
> /usr/share/texlive/texmf-dist/tex/latex/lwarp/lwarp-hanging.sty
> texlive-xetex:
> /usr/share/texlive/texmf-dist/tex/xetex/xetexko/xetexko-hanging.sty
> texlive-latex-extra: /usr/share/texlive/texmf-dist/tex/latex/tabu/tabu.sty
> texlive-latex-extra:
> /usr/share/texlive/texmf-dist/tex/latex/stackengine/stackengine.sty
> texlive-latex-extra:
> /usr/share/texlive/texmf-dist/tex/latex/tabstackengine/tabstackengine.sty
>
> You can see the package name and the installation path.

Looks as if all necessary .sty files were in texlive-latex-extra. Do you
have that package?

One more thought: what if your bleeding edge doxygen version generates
"newer" latex code that your latex version doesn't understand? Can you
downgrade and use an older doxygen version again?

[Greg Ercolano]

On 08/05/18 17:15, Albrecht Schlosser wrote:
> Looks as if all necessary .sty files were in texlive-latex-extra. Do you
> have that package?

Nope -- here's the big 'yum search texlive' output on my machine:
http://seriss.com/people/erco/tmp/scilinux7-yum-search-texlive.txt

> One more thought: what if your bleeding edge doxygen version generates
> "newer" latex code that your latex version doesn't understand? Can you
> downgrade and use an older doxygen version again?

Yes! Good call.

Reverting to the older doxygen does seem to get rid of the complaints
about Fl_File_Chooser, and 'make pdf' now works with no errors.

Interesting -- I didn't think doxygen + latex/texlive needed to be
so.. in sync? I thought latex was latex.. silly me!

The OS installed doxygen (1.8.5) was still in /usr/bin,
so I just renamed away the newer one in /usr/local/bin (1.8.15),
reran configure (to get the new path), and then 'make pdf' worked fine,
no warnings or errors:

[erco@harris] # make pdf

Generating Doxybook ...
Generating PDF documentation ...

[erco@harris] # ls -la fltk.pdf
-rw-r--r--. 1 root root 4850608 Aug 5 18:53 fltk.pdf

..which is now 1177 pages.

That seemed to get rid of the "black boxes" too, and gained an index
at the /end/ of the pdf file (which was missing from my previous experiments).

I didn't even need to pull your latest git commit, though I will later
just to see if there's a difference.

So I'd call that solved..!

[Albrecht Schlosser]

On 06.08.2018 04:04 Greg Ercolano wrote:
> On 08/05/18 17:15, Albrecht Schlosser wrote:
>> One more thought: what if your bleeding edge doxygen version generates
>> "newer" latex code that your latex version doesn't understand? Can you
>> downgrade and use an older doxygen version again?
>
> Yes! Good call.
>
> Reverting to the older doxygen does seem to get rid of the complaints
> about Fl_File_Chooser, and 'make pdf' now works with no errors.

Great!

> The OS installed doxygen (1.8.5) was still in /usr/bin,
> so I just renamed away the newer one in /usr/local/bin (1.8.15),
> reran configure (to get the new path), and then 'make pdf' worked fine,

> [...]

FWIW: I installed all different doxygen versions in their own paths
(even with `make install`) after configuring each doxygen build with
another prefix. Then I can use CMake to pick the version I want and run
`make pdf' or `ninja pdf'.

With cmake-gui you can easily (re-)configure to test another doxygen
version or you can even have different build dir's for different doxygen
versions. The latter is what I was using to test the FLTK docs.

With configure it's likely `./configure --with-doxygen=/path/to/doxygen'
or you can edit 'makeinclude' after configure.

> I didn't even need to pull your latest git commit, though I will later
> just to see if there's a difference.
>
> So I'd call that solved..!

Meanwhile I'd say "yes". I pushed another commit that *really* fixed the
underlying "caption" cause, but now it gets weirder and weirder.

The "caption" issue was that doxygen can't render class names (and
supposedly other object names with special formatting and links) in the
caption. Unfortunately all three ocurrences of <caption> tags in HTML
tables had the class name in their text. Otherwise it would likely have
been easier to isolate the real problem. My latest commit removes the
class names from the captions and re-enables them which means we have a
working pdf generation again.

However, my further tests revealed:

(1) doxygen 1.8.14 is seriously broken. This version issues warnings and
generates wrong (latex) code and is unusable for our (pdf) docs. An
example in my tests yields:

Generating docs for compound Fl_Input...
/home/albrecht/git/fltk-test/doxy_test/html_comment_in_table.h:18:
warning: expected <tr> or <caption> tag but found <br> instead!
/home/albrecht/git/fltk-test/doxy_test/html_comment_in_table.h:18:
warning: Unexpected tag <caption> found
/home/albrecht/git/fltk-test/doxy_test/html_comment_in_table.h:18:
warning: Unexpected tag </caption> found
/home/albrecht/git/fltk-test/doxy_test/html_comment_in_table.h:29:
warning: expected <tr> or <caption> tag but found <br> instead!
/home/albrecht/git/fltk-test/doxy_test/html_comment_in_table.h:29:
warning: Unexpected tag <caption> found
/home/albrecht/git/fltk-test/doxy_test/html_comment_in_table.h:29:
warning: Unexpected tag </caption> found

$ grep -n br html_comment_in_table.h
4: Doxygen Error Report: HTML comment breaks parser.
11: HTML comment within table breaks parser.

File contents:

1 /**
2 \file html_comment_in_table.h
3
4 Doxygen Error Report: HTML comment breaks parser.
5
6 Doxygen version: 1.8.14.
7
8 */
9
10 /**
11 HTML comment within table breaks parser.
12
13 <table>
14 <!-- This is a comment. -->
15 <caption align="top">This is a table caption.</caption>
16 <tr>
17 <td nowrap="nowrap" width="1%"><b>Mouse button 1</b></td>
18 <td>Moves the cursor to this point. ...</td>
19 </tr>
20 </table>
21 */
22
23 class Fl_Input {
24 int unused;
25 public:
26 Fl_Input(int, int, int, int, const char * = 0);
27 };
28
29 // End of file


(2) Doxygen 1.8.15 (git master, not released) is not much better. I can
replicate the error message you mentioned before. This seems like a
parser error as well. But it's not yet released, so maybe there's still
hope.

/home/albrecht/git/fltk-test/src/Fl_File_Chooser2.cxx:190: warning: no

uniquely matching class member found for

void Fl_File_Chooser::filter(char< em > p)

Possible candidates:
void Fl_File_Chooser::filter(const char *p)' at line 137 of file

/home/albrecht/git/fltk-test/FL/Fl_File_Chooser.H

const char * Fl_File_Chooser::filter()' at line 138 of file

/home/albrecht/git/fltk-test/FL/Fl_File_Chooser.H

The function reference in the file is obviously correct, but it seems
that the parser is wrong: "void Fl_File_Chooser::filter(char< em > p)".

Where does "char< em >" come from? The source file is different.

Strange...

At least 1.8.13 (installed in Ubuntu 18.04 LTS) seems to work well
except for the <caption> bug.

[Greg Ercolano]

On 08/05/18 16:40, Albrecht Schlosser wrote:
> (2) the <CAPTION> statement in the two FLTK header files
>
> There were no helping error messages. For the 2nd issue there were
> basically *NO* error messages at all except something like "A fatal
> error has occurred" or similar.

Hmm, I tried putting back the classname "Fl_Tree" for the caption
in the Fl_Tree table, and 1.8.5 doxygen seemed to have no problem
generating the html:

# make html
Generating Doxyfile ...
Generating HTML documentation...

# doxygen -v
1.8.5

So perhaps that's a bug in a specific doxygen version, and not 1.8.*
(as the new committed comment shows)

However, I am noticing that, regardless of the caption change,
the PDF docs aren't showing the html TABLE /at all/.. it's skipped completely.
This screenshot compares the html and pdf docs for Fl_Tree's keyboard binding table:

http://seriss.com/people/erco/tmp/fltk-pdf-vs-html.png

I thought doxygen/latex, in all its massive glory, was actually converting
html tags into whatever was needed for the final output, but it seems not..?

I guess I should look into converting that HTML table into a regular
ascii art style table, so the PDF docs aren't deficient.

There's other weird issues too I need to fix, such as code examples
getting leading comment *'s caught in them, and "\image html" doxygen
commands not being expanded, probably due to the 4 spaces+ indenting
which apparently triggers verbatim preformatted text in doxygen.

[Greg Ercolano]

On 08/06/18 09:45, Greg Ercolano wrote:
> There's other weird issues too I need to fix, such as code examples
> getting leading comment *'s caught in them,

Ugh, this is a doxygen bug with "///" style commenting.

In the code, the doxygen comment is:


/// Returns the last item in the tree.
///
/// This can be used to walk the tree in reverse, e.g.
///
/// \code
/// for ( Fl_Tree_Item *item = tree->last(); item; item = tree->prev() )
/// printf("Item: %s\n", item->label());
/// \endcode
/// [..]

..the resulting html docs end up having '*'s in front of every
code example line:

--- snip
Returns the last item in the tree.

This can be used to walk the tree in reverse, e.g.

* for ( Fl_Tree_Item *item = tree->last(); item; item = tree->prev() )
* printf("Item: %s\n", item->label());
*
--- snip

What the heck? When I change that to:

/**
Returns the last item in the tree.
This can be used to walk the tree in reverse, e.g.
\par
\code
for ( Fl_Tree_Item *item = tree->last(); item; item = tree->prev() )
printf("Item: %s\n", item->label());
\endcode
[..]
*/

..then the leading asterisks disappear.

[Albrecht Schlosser]

On 06.08.2018 18:45 Greg Ercolano wrote:
> On 08/05/18 16:40, Albrecht Schlosser wrote:
>> (2) the <CAPTION> statement in the two FLTK header files
>>
>> There were no helping error messages. For the 2nd issue there were
>> basically *NO* error messages at all except something like "A fatal
>> error has occurred" or similar.
>
> Hmm, I tried putting back the classname "Fl_Tree" for the caption
> in the Fl_Tree table, and 1.8.5 doxygen seemed to have no problem
> generating the html:
>
> # make html
> Generating Doxyfile ...
> Generating HTML documentation...
>
> # doxygen -v
> 1.8.5
>
> So perhaps that's a bug in a specific doxygen version, and not 1.8.*
> (as the new committed comment shows)

I have to admit that my comment was not very specific. Since I didn't
know nor want to enumerate all concerned doxygen versions I used "1.8.*"
which should mean "some or all 1.8.x" versions.

I didn't see the "caption" issue with HTML output - I believe it always
worked with that. The only issue was with PDF output.

In my old doxygen 1.8.6 version it did _not_ crash, but I didn't check
if the caption was formatted or even if these particular table(s)
existed in the PDF output. We may want to check this so we know which
versions of doxygen work and which ones fail.

> However, I am noticing that, regardless of the caption change,
> the PDF docs aren't showing the html TABLE /at all/.. it's skipped completely.
> This screenshot compares the html and pdf docs for Fl_Tree's keyboard binding table:
>
> http://seriss.com/people/erco/tmp/fltk-pdf-vs-html.png
>
> I thought doxygen/latex, in all its massive glory, was actually converting
> html tags into whatever was needed for the final output, but it seems not..?

I think the correct statement would be something like:

- doxygen has its own syntax but can also interpret html tags
- doxygen syntax is preferred
- doxygen converts the input files to LaTeX (and/or HTML)
- LaTeX produces the PDF output file.

Since doxygen and latex are developed independently it's hard to say
which combination of versions (together with lex, bison, and maybe more)
gives the best results.

> I guess I should look into converting that HTML table into a regular
> ascii art style table, so the PDF docs aren't deficient.

I think doxygen has its own table syntax but I'm not sure about that. I
wouldn't want to use ASCII art. The tables, as they are now, look
certainly better (if they exist and are complete). We may find "good"
doxygen versions and document that one of these versions is required for
"the best experience". :-)

I can see big differences between doxygen 1.8.6 and 1.8.13 on the same
system (i.e. with the same lexers and latex versions) in the PDF output:

1.8.6: 5.027.225 bytes, 1.236 pages
1.8.13: 5.263.775 bytes, 1.429 pages

1.8.6 has the Fl_Input "Table 31.1 Keyboard and mouse bindings"
(complete, page 647), but not the 2nd Fl_Input table. The caption is
below the table.

1.8.13 has both Fl_Input tables, but the first "Table 31.172 Keyboard
and mouse bindings" is incomplete (page 721, cut off after "Delete" at
the page boundary). The 2nd Fl_Input "Table 31.173 Platform specific..."
appears to be complete on the next page (p. 722). The caption is above
the tables.

Fl_Tree:
1.8.6 doesn't have the table (page 969).
1.8.13 has the complete table on page 1128.

If you want me to send the PDF files to you, drop me a mail.

> There's other weird issues too I need to fix, such as code examples
> getting leading comment *'s caught in them, and "\image html" doxygen
> commands not being expanded, probably due to the 4 spaces+ indenting
> which apparently triggers verbatim preformatted text in doxygen.

Yes, the "max. 4 spaces indent" issue was introduced by doxygen but I
don't recall in which version. If you can fix such issues that would be
a big step forward. But I would suggest that you use a newer (i.e.
"better") doxygen version before you work on issues that are fixed in
newer versions.

Nothing is perfect. I think we can only try to find "good" versions and
try to use such "good" versions to generate the release(d) docs.
Everything else is not in our hands because users have so many different
systems and configurations.

[Albrecht Schlosser]

I suggest to do that (if you have the time and are willing to do it).
Our doxygen comment style is officially /** ... */ without leading
asterisks in every line. Matt did a great job deleting such leading
asterisks.

There are other issues, and I thought some of the problems had to do
with this: long lines of '////////////////' which should be avoided,
according to the doxygen docs, IIRC. The problem with this is that the
first three slashes introduce the doxygen comment, and the following
slashes are ... documentation? It turned out that this was not the case,
but I believe I read a warning not to do this.

[Greg Ercolano]

On 08/06/18 10:54, Albrecht Schlosser wrote:
>> I guess I should look into converting that HTML table into a regular
>> ascii art style table, so the PDF docs aren't deficient.
>
> I think doxygen has its own table syntax but I'm not sure about that.

It does in its markdown support, and I've used it before,
but it's kinda.. temperamental? Doesn't always do what you want.

I made a change (see below) to use the markdown stuff, but I'll
need to check it in older doxygen's, as I'm not so sure how well
markdown is supported in older versions. I think doxygen table
stuff might be relatively new, not sure.

> I wouldn't want to use ASCII art. The tables, as they are now, look
> certainly better (if they exist and are complete). We may find "good"
> doxygen versions and document that one of these versions is required for
> "the best experience". :-)

But hmm, did you not find the table completely missing in the PDF
version?

> I can see big differences between doxygen 1.8.6 and 1.8.13 on the same
> system (i.e. with the same lexers and latex versions) in the PDF output:
>
> 1.8.6: 5.027.225 bytes, 1.236 pages
> 1.8.13: 5.263.775 bytes, 1.429 pages

Ya, I get a lot of page and size variations too.

> Fl_Tree:
> 1.8.6 doesn't have the table (page 969).
> 1.8.13 has the complete table on page 1128.

I've committed r13008 to redo the table using doxygen's markdown.
I still need to check it in older releases; see how that goes.

I tend to not use doxygen features if they're not well supported,
and I'm often surprised when old stuff that worked fine suddenly
breaks.

> If you want me to send the PDF files to you, drop me a mail.

That's OK.

>
>> There's other weird issues too I need to fix, such as code examples
>> getting leading comment *'s caught in them, and "\image html" doxygen
>> commands not being expanded, probably due to the 4 spaces+ indenting
>> which apparently triggers verbatim preformatted text in doxygen.
>
> Yes, the "max. 4 spaces indent" issue was introduced by doxygen but I
> don't recall in which version.

Yes -- and it has problems in some contexts; I've reported a few
things along these lines on the doxygen mailing list.

> If you can fix such issues that would be
> a big step forward.

See above commit -- just for Fl_Tree's docs.

> But I would suggest that you use a newer (i.e.
> "better") doxygen version before you work on issues that are fixed in
> newer versions.

"Meh".. seems as many things get fixed also get broken in doxygen,
it's seeming more and more like chasing a chicken around the yard
to keep things working.

My usual modus operandi with programming is to try new features,
then walk back if there's /any/ problems/bugs, seeking the least
common denominator, and simply living with that, and pretending the
new but sometimes broken features don't exist.

"There's always ascii art" is my fallback, lol.

[Greg Ercolano]

On 08/06/18 11:15, Greg Ercolano wrote:
>> Fl_Tree:
>> 1.8.6 doesn't have the table (page 969).
>> 1.8.13 has the complete table on page 1128.
>
> I've committed r13008 to redo the table using doxygen's markdown.
> I still need to check it in older releases; see how that goes.

Here's the result with above commit in 1.4.x-svn current, pdf + html side by side:
http://seriss.com/people/erco/tmp/fltk-pdf-vs-html-2.png

The table looks nice in both versions, but I ran into a few new problems
I've never seen before; the table either splitting across the page (header
on one page, data on the other), or as shown above, the table on its own page,
but a completely blank page between the table and the content preceding it.

I imagine results will vary, but I'm often surprised when this
kind of thing happens.

I brought my Fl_Tree doxygen mods over to your current git branch and rebuilt
the pdf, getting this nicer result (probably by chance?):
http://seriss.com/people/erco/tmp/fltk-Fl_Tree-binding-table-1.4.x-git.png

I guess one of your changes must've been to the default font;
I notice with the git branch, the PDF font is sans serif,
and with svn current, it's serif (ugly IMHO). I prefer the sans serif
myself; much easier on the eyes.

Unless you're waiting for some reason, I'd suggest you commit your git
branch to SVN.

[Albrecht Schlosser]

On 06.08.2018 20:57 Greg Ercolano wrote:
> On 08/06/18 11:15, Greg Ercolano wrote:
>>> Fl_Tree:
>>> 1.8.6 doesn't have the table (page 969).
>>> 1.8.13 has the complete table on page 1128.
>>
>> I've committed r13008 to redo the table using doxygen's markdown.
>> I still need to check it in older releases; see how that goes.
>
> Here's the result with above commit in 1.4.x-svn current, pdf + html side by side:
> http://seriss.com/people/erco/tmp/fltk-pdf-vs-html-2.png
>
> The table looks nice in both versions, but I ran into a few new problems
> I've never seen before; the table either splitting across the page (header
> on one page, data on the other), or as shown above, the table on its own page,
> but a completely blank page between the table and the content preceding it.

Think of testing newer doxygen/latex versions as well to avoid wasting
too much time with bugs in older versions.

> I imagine results will vary, but I'm often surprised when this
> kind of thing happens.
>
> I brought my Fl_Tree doxygen mods over to your current git branch

Did you? I don't see a commit. Please push your commit(s) to GitHub as
well so I don't have to merge (I take it you merged some conflicts).

> and rebuilt the pdf, getting this nicer result (probably by chance?):
> http://seriss.com/people/erco/tmp/fltk-Fl_Tree-binding-table-1.4.x-git.png
>
> I guess one of your changes must've been to the default font;
> I notice with the git branch, the PDF font is sans serif,
> and with svn current, it's serif (ugly IMHO). I prefer the sans serif
> myself; much easier on the eyes.

I noticed this as well, but I'm not aware I that *I* changed something
related to fonts. It's likely that the generation of the latex header
file changed things. I'm fine with the "new look" as well, so we should
let it as-is.

> Unless you're waiting for some reason, I'd suggest you commit your git
> branch to SVN.

Since you committed your changes and wrote that you brought it over to
the git branch, I'm looking forward to see your commit and will then
copy the diffs back to svn. After that we can delete the git branch.

And, BTW, I had a few long days in the past. It's enough for today, I
will continue tomorrow.

[Greg Ercolano]

On 08/06/18 12:16, Albrecht Schlosser wrote:

>> I brought my Fl_Tree doxygen mods over to your current git branch
>
> Did you? I don't see a commit.

Not as a commit, just copied my changes from my fltk-1.4.x-svn
directory over to my fltk-1.4.x-git directory to test.

I wasn't doing any commits to git because I figure there's only
one master right now, svn. So to see my commit, see svn r13008
which just has mods to FL/Fl_Tree.H + src/Fl_Tree.cxx

I can push git mods if you want, but I didn't want to have multiple
masters.. my mind is muddled enough with all this, lol.

For sure my older machine with doxygen 1.6.1 doesn't support
that markdown table.. but that is a MUCH older release that
doesn't look very good anyway; it has many old doxygen bugs.

Gotta say, it's much easier to /read/ the markdown version in
the docs, and it's shorter, so I might leave it.

>> Unless you're waiting for some reason, I'd suggest you commit your git
>> branch to SVN.
>
> Since you committed your changes and wrote that you brought it over to
> the git branch, I'm looking forward to see your commit and will then
> copy the diffs back to svn. After that we can delete the git branch.

I meant merge your git branch mods into svn current, so they
end up in the master along with my mods.

I'll try pushing my mods up to your git, but I really didn't want
to use that for production ;)

[Albrecht Schlosser]

On 06.08.2018 21:42 Greg Ercolano wrote:
> On 08/06/18 12:16, Albrecht Schlosser wrote:
>>> I brought my Fl_Tree doxygen mods over to your current git branch
>>
>> Did you? I don't see a commit.
>
> Not as a commit, just copied my changes from my fltk-1.4.x-svn
> directory over to my fltk-1.4.x-git directory to test.
>
> I wasn't doing any commits to git because I figure there's only
> one master right now, svn. So to see my commit, see svn r13008
> which just has mods to FL/Fl_Tree.H + src/Fl_Tree.cxx
>
> I can push git mods if you want, but I didn't want to have multiple
> masters.. my mind is muddled enough with all this, lol.

True. There can be only one (master). ;-)
https://youtu.be/sqcLjcSloXs

I assumed that we both had changes in the same files (at least
Fl_Tree.H) and since you had already done the merge I thought it was
easier if you just committed it to the git repo and I ported it back to
svn...

Thanks for committing. Looks good!

See attached screenshot doxygen_tables.png generated with doxygen 1.8.13
on Ubuntu 18.04 LTS.

> For sure my older machine with doxygen 1.6.1 doesn't support
> that markdown table.. but that is a MUCH older release that
> doesn't look very good anyway; it has many old doxygen bugs.
>
> Gotta say, it's much easier to /read/ the markdown version in
> the docs, and it's shorter, so I might leave it.

I think we can stay with these doxygen tables.

If an older doxygen version didn't understand the markdown it would
still be ASCII art, wouldn't it? It would likely suffice from
proportional fonts, but anyway: better than other issues we saw.

>>> Unless you're waiting for some reason, I'd suggest you commit your git
>>> branch to SVN.
>>
>> Since you committed your changes and wrote that you brought it over to
>> the git branch, I'm looking forward to see your commit and will then
>> copy the diffs back to svn. After that we can delete the git branch.
>
> I meant merge your git branch mods into svn current, so they
> end up in the master along with my mods.
>
> I'll try pushing my mods up to your git, but I really didn't want
> to use that for production ;)

Note that the fltk-test repository is only for tests, not for production.

As such a test I took all the missing svn commits (I probably missed one
so far, I'll look into it later), committed them to a local branch
originating from the 'master' branch when the fltk-test.git repo was
"forked" and merged them into master. There were a few minor merge
conflicts I could fix easily.

As a second test I merged branch doxygen_pdf into master. There were no
conflicts although "your" mods were in both branches (merged into master
from svn and in doxygen_pdf). Git is smart enough to know this.

Current state of fltk-test.git (master) is complete as of svn r13010.

There are a few other mods (test commits) that don't matter.

[Greg Ercolano]

On 08/07/18 02:03, Albrecht Schlosser wrote:
> True. There can be only one (master). ;-)
> https://youtu.be/sqcLjcSloXs

:D

> Thanks for committing. Looks good!
>
> See attached screenshot doxygen_tables.png generated with doxygen 1.8.13
> on Ubuntu 18.04 LTS.

Great, it even split the table correctly across the page,
repeating the header.. wonderful.

> If an older doxygen version didn't understand the markdown it would
> still be ASCII art, wouldn't it?

Unfortunately no, the old version turns the entire table
into a *single line of proportional width text*.

> Current state of fltk-test.git (master) is complete as of svn r13010.
> There are a few other mods (test commits) that don't matter.

Great, tomorrow I'll pull svn and retest just to verify.

I'm torn about converting the Fl_Tree.{cxx,H} docs into /** */
style. For one, it's a BIG job because there's a lot of docs.

But more importantly, I really don't like the /** */ comment style
in this particular context, because Fl_Tree has so many docs + examples..

Quite simply, it's hard to tell docs from code, esp. when
there's lots of "\code" examples.

I prefer the /// style comments in Fl_Tree because that stark
line of ///'s down the left margin makes it so clear it's doxygen
commenting, even within \code examples.

And after my commit to fix the docs, I can see I /really/ dislike
the /** */ result.. it's hard to see docs from code when scrolling
around.

And since Fl_Tree may still have a few rounds of heavy dev needed,
I remember how distracting the comments were when needing to zip
up and down the files searching for small methods and make small
changes.

I'd actually spent a bit of time hacking VI macros to make it easy
to toggle doxygen comments on and off.. and it worked better when
there were ///'s vs /** */ (easier to detect line-at-a-time).

I should really research which doxygen versions have that "*"
bug with /// comments + \code, and if it isn't fixed in current,
report the bug to them because it's super annoying.

[Greg Ercolano]

On 08/07/18 02:42, Greg Ercolano wrote:
> I should really research which doxygen versions have that "*"
> bug with /// comments + \code, and if it isn't fixed in current,
> report the bug to them because it's super annoying.

Looks like this bad behavior was fixed in doxygen 1.8.15,
so the reasons for that commit I made seem less important,
as it just chases a bug that was only in a few doxygen versions.

I might revert that commit mainly for the reasons I'd cited,
and also for consistency because the bulk of the code still
has /// style comments.