X-Authentication-Warning: delorie.com: mail set sender to geda-user-bounces using -f
X-Recipient: geda-user AT delorie DOT com
X-Mailer: exmh version 2.7.2 01/07/2005 (debian 1:2.7.2-18) with nmh-1.3
X-Exmh-Isig-CompType: repl
X-Exmh-Isig-Folder: inbox
To: geda-user AT delorie DOT com
Subject: Re: [geda-user] libgeda documentation
In-reply-to: <50A6EC60.9080503@sbcglobal.net>
References: <20121113195022 DOT 2B2CF813A49B AT turkos DOT aspodata DOT se> <50A2E0FC DOT 5050108 AT sbcglobal DOT net> <20121114090659 DOT BF2CF813A49D AT turkos DOT aspodata DOT se> <50A3FD26 DOT 5000305 AT sbcglobal DOT net> <20121115195816 DOT 29A428117B46 AT turkos DOT aspodata DOT se> <50A6A5AE DOT 506 AT sbcglobal DOT net> <20121116221659 DOT DDD8181345FC AT turkos DOT aspodata DOT se> <50A6EC60 DOT 9080503 AT sbcglobal DOT net>
Comments: In-reply-to "Girvin R. Herr" <girvin DOT herr AT sbcglobal DOT net>
   message dated "Fri, 16 Nov 2012 17:46:08 -0800."
Mime-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Message-Id: <20121117152957.894028130EDB@turkos.aspodata.se>
Date: Sat, 17 Nov 2012 16:29:57 +0100 (CET)
From: karl AT aspodata DOT se (Karl Hammar)
X-Virus-Scanned: ClamAV using ClamSMTP
Reply-To: geda-user AT delorie DOT com
Errors-To: nobody AT delorie DOT com
X-Mailing-List: geda-user AT delorie DOT com
X-Unsubscribes-To: listserv AT delorie DOT com
Precedence: bulk

Girvin Herr:
> Karl Hammar wrote:
> <snip>
> >   ./configure --enable-doxygen --disable-update-xdg-database
> >  make
> > ...
> >  make doxygen
> > ... millons of lines passing by ...
> >
> > Two errors (the first one fixed by installing inkscape):
> >  ! LaTeX Error: File `o_attrib_overview' not found.

The one above did not show up in the git version.

> >  sh: dot: command not found
> >
> > So that worked (sort of...).
> >
> >  cd libgeda/docs/
> >  make doxygen
> >
> > same.
> >
> > What do you get if you run (in top dir.):
> >   
> That's when I get the
> 
>     make: *** No rule to make target `doxygen'.  Stop.

Can you tell me what source archive you downloaded so I can test for 
myself, or perhaps can you try the git version since I had better luck 
with it.

> I got the same results as you did when I tried the "make doxygen" target 
> in the libgeda/docs" directory.  Lots of errors and the missing "dot" 
> program at least.

Ok, we should add a test for dot which is part of graphviz.

Some of the errors seems to be misspellings, e.g.:

$ fgrep -C1 '\parma' gattrib/src/s_object.c
 * \param new_attrib_name Name of attribute to add
 * \parma new_attrib_value Value of attribute to add
 * \todo Do I really need separate fcns for comps, nets, and

> I just searched for the doxygen Makefile target and only found it in the 
> "libgeda/docs" Makefile.  There was nothing in the "libgeda" Makefile, 
> and it was defined, but not a target in the main Makefile.  That is 
> probably why I got the "No Rule" message.  There seems to be a 
> disconnect between the main Makefile and the libgeda/docs Makefile.  
> Could that be from a "silent" test failure by configure?  I also noticed 
> the other html documentation (docs/wiki) is already in html format.  The 
> docs/wiki Makefile.am lists all the wiki files as data, so it is copied 
> by make during the build process - no need for doxygen at build time.
> 
> <snip>
> > Yes, though it seems the configure doesn't check for every programs
> > needed.
> >   
> I would agree to that.  Since I do not have the inkscape program, that 
> may be another hangup to generating these documents.  Another 

Yes, but the Makefile says inkscape || convert, but for me one file was 
not found by pdflatex. Do you have convert (part of ImageMagic)
installed? If so it explains why it didn't complain about inkscape.

inkscape does a better conversion job than convert since convert 
generates bitmaps, so we should probably recommend the user to install 
inkscape.

Also, when in libgeda/docs, 

 $ make doxygen
 Creating doxygen documentation for libgeda...
 cd images && make images
 make[1]: Entering directory `/Net/git/geda-gaf/libgeda/docs/images'
 inkscape -e o_attrib_overview.png o_attrib_overview.svg  ||  convert o_attrib_overview.svg o_attrib_overview.png
 /bin/sh: inkscape: command not found
...

the "command not found" is misleading since convert is installed.
Instead of (libgeda/docs/images/Makefile) saying:

.svg.png:
        inkscape -e $@ $<  ||  convert $< $@

it should say something like:

.svg.png:
	if [ -x "`which inkscape`" ]; then inkscape -e $@ $< ; else  convert $< $@; fi

dito for .svg.pdf.

> possibility is that configure is checking for the programs, but not 
> reporting the errors, just continuing quietly without doing the API 
> document build.

It doesn't check for dot and it accepts convert as an alternative for 
inkscape.

> IMHO: It would seem to be a good idea that if the user specifies 
> "--enable-doxygen" to configure (implying documents are required) _and_ 
> the files needed to build those doxygen files are not found by 
> configure, that would be grounds for a fatal configure error with a 
> resulting error message!  At least display a warning message at the end 
> of configure that documentation is not to be built.  I have seen that 
> done also.

Agreed.

> I see in my "configure.log" file that the search for inkscape had 
> failed, but doxygen was okay. 
> I also see in "configure.ac", that doxygen is implicitly checked:
> 
>     AX_OPTION_DOXYGEN
> 
> , but no other, like "dot".  Although configure seems to check for 
> inkscape, it is not implicit in the "configure.ac" file.  So something 
> else is going on in the background for implied dependencies.

The check comes from m4/geda-doxygen.m4

Regards,
/Karl Hammar

-----------------------------------------------------------------------
Aspö Data
Lilla Aspö 148
S-742 94 Östhammar
Sweden
+46 173 140 57