New repository, "make doc"

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

New repository, "make doc"

Dr Rainer Woitok
Greetings,

having seen Steve  mention the URL of the  new Git  source repository, I
decided to clone a new local GPSBabel repository  from there.   However,
the new Git repository  contains an additional "gpsbabel/" sub-directory
on top of the former directory hierarchy.  That's not a real problem for
me, because  locally I'm  using Mercurial anyway,  and while  converting
from Git to Mercurial  I can easily get rid  of this additional sub-dir-
ectory.  But it is perhaps not what other users are expecting.

The real problem started  when I ran  "make doc".   I got wagon loads of
error messages  (no,  for some reason or other  I didn't run  "make doc"
from the old SVN repository):

mkdir -p /home/Rainer/repo/gpsbabel/doc/htmldoc-development
perl xmldoc/makedoc
xmlwf xmldoc/readme.xml #check for well-formedness
xmllint --noout --valid xmldoc/readme.xml     #validate
xsltproc \
 --stringparam base.dir "/home/Rainer/repo/gpsbabel/doc/htmldoc-development/" \
 --stringparam root.filename "index" \
 xmldoc/babelmain.xsl \
 xmldoc/readme.xml
xmldoc/readme.xml:1: element preface: validity error : ID Introduction already defined
xmldoc/readme.xml:3: element section: validity error : ID The_Problem already defined
xmldoc/readme.xml:24: element section: validity error : ID The_Solution already defined
xmldoc/readme.xml:1: element chapter: validity error : ID Getting_and_Building already defined
xmldoc/readme.xml:3: element sect1: validity error : ID Download already defined
xmldoc/readme.xml:16: element sect1: validity error : ID Source already defined
xmldoc/readme.xml:1: element chapter: validity error : ID Usage already defined
xmldoc/readme.xml:3: element sect1: validity error : ID Invocation already defined
xmldoc/readme.xml:71: element example: validity error : ID linux_download_from_magellan already defined
xmldoc/readme.xml:76: element example: validity error : ID windows_download_from_magellan already defined

... <altogether 11968 messages of the above kind> ...

Making portrait pages on USletter paper (8.5inx11in)
fop -q -fo gpsbabel.fo -pdf gpsbabel.pdf
make: fop: Command not found
Makefile:267: recipe for target 'gpsbabel.pdf' failed
make: *** [gpsbabel.pdf] Error 127

And as a result of "make doc" my  "./doc/htmldoc-development/" directory
now contains 213 files "*.html", all with identical contents:

<?php
require("../lib/smarty_common.php");
$smarty->display($template);
?>

So apparently I'm requiring Smarty  (as well as PHP)  to be able to make
the HTML documentation,  together with "fop" to make the PDF documentat-
ion.   What other software prerequisites   will I find documented in the
documentation when I ever manage to build it? :-)

Wishlist:

1. "./configure"  should find out  whether or not  Smarty,  PHP,  "fop",
   "xmlwf", "xmllint", and "xsltproc"  (and maybe even Perl)  are avail-
   able at all and should create Perl script "xmldoc/makedoc" or an add-
   itional Shell script in  such a way that  it complains  about missing
   software in advance and if applicable, points out to use new make re-
   cipies "make doc-html" or "make doc-pdf" directly to get the same am-
   ount of documentation but less error messages.  Regarding "fop" there
   are already some such comments in file "Makefile" which could be used
   as a start (but these comments also show how fragile making this doc-
   umentation currently is).

2. "make  doc" should at  least  create or  provide traditional Unix man
   pages readable with "man"  (these are  creatable,  for instance, with
   "DocBook" (which you seem to use anyway) and could already be includ-
   ed in the source repository).

3. Making the documentation should not depend on a plethora of different
   utilities which only cooperate when specific version requirements are
   met.   Documentation can well  be more advanced  than the ancient and
   perhaps spartanic "troff" man pages,  but ideally the software requi-
   rements for creating the documentation should only consist of a sing-
   le documentation package  plus the interpreter  it is written in (for
   instance "docutils", which requires Python but nothing else).

4. Both, making and  reading the documentation  should not  depend on an
   Internet connection but should be possible offline.

Well, I'm aware it's not Christmas time, so these wishes will not be met
anytime soon, but as a user of a software  providing as complex features
as GPSBabel does, I feel a bit lost without documentation which is both,
up to date and offline.

Sincerely,
  Rainer

 ----------------------------------------------------------------------
| Rainer M Woitok                | Phone : (+49 60 93) 487 95 95       |
| Kolpingstraße 3                | Mobile: (+49 172) 813 6 831         |
| D-63846 Laufach                | Mail  : [hidden email]     |
| Germany                        |                                     |
 ----------------------------------------------------------------------

------------------------------------------------------------------------------
_______________________________________________
Gpsbabel-misc mailing list http://www.gpsbabel.org
[hidden email]
To unsubscribe, change list options, or see archives, visit:
https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc
Reply | Threaded
Open this post in threaded view
|

Re: New repository, "make doc"

tsteven4-2
Rainer,

You can now see our ci script here:
https://github.com/gpsbabel/gpsbabel/blob/master/.travis.yml
It builds on ubuntu precise.  The extra packages over what the travis precise build requires are shown in line 7.
The script that does the meat is
https://github.com/gpsbabel/gpsbabel/blob/master/gpsbabel/build_and_test
build and test does build the document (make doc) and the html equivalent (make gpsbabel.html).
If you go to this page
https://travis-ci.org/gpsbabel/gpsbabel
then you can click on one of the build job numbers, e.g. just now the numbers available were 16.1 or 16.2.  This will take you to the build log and you can see the dialog from our ci build.

If you go here
http://www.gpsbabel.org/readme.html
you can find a link

and you can download the pdf of the manual from the last release for your offline reading pleasure.

Robert is usually the only person that builds the document (pdf & html).  I added it to our jenkins regression (which was the basis for our current travis regression) just so we don't let any issues pile up until the next release.

Steve

On 8/19/2015 7:42 AM, Dr Rainer Woitok wrote:
Greetings,

having seen Steve  mention the URL of the  new Git  source repository, I
decided to clone a new local GPSBabel repository  from there.   However,
the new Git repository  contains an additional "gpsbabel/" sub-directory
on top of the former directory hierarchy.  That's not a real problem for
me, because  locally I'm  using Mercurial anyway,  and while  converting
from Git to Mercurial  I can easily get rid  of this additional sub-dir-
ectory.  But it is perhaps not what other users are expecting.

The real problem started  when I ran  "make doc".   I got wagon loads of
error messages  (no,  for some reason or other  I didn't run  "make doc"
from the old SVN repository):

mkdir -p /home/Rainer/repo/gpsbabel/doc/htmldoc-development
perl xmldoc/makedoc
xmlwf xmldoc/readme.xml		#check for well-formedness
xmllint --noout --valid xmldoc/readme.xml    	#validate
xsltproc \
 --stringparam base.dir "/home/Rainer/repo/gpsbabel/doc/htmldoc-development/" \
 --stringparam root.filename "index" \
 xmldoc/babelmain.xsl \
 xmldoc/readme.xml
xmldoc/readme.xml:1: element preface: validity error : ID Introduction already defined
xmldoc/readme.xml:3: element section: validity error : ID The_Problem already defined
xmldoc/readme.xml:24: element section: validity error : ID The_Solution already defined
xmldoc/readme.xml:1: element chapter: validity error : ID Getting_and_Building already defined
xmldoc/readme.xml:3: element sect1: validity error : ID Download already defined
xmldoc/readme.xml:16: element sect1: validity error : ID Source already defined
xmldoc/readme.xml:1: element chapter: validity error : ID Usage already defined
xmldoc/readme.xml:3: element sect1: validity error : ID Invocation already defined
xmldoc/readme.xml:71: element example: validity error : ID linux_download_from_magellan already defined
xmldoc/readme.xml:76: element example: validity error : ID windows_download_from_magellan already defined

... <altogether 11968 messages of the above kind> ...

Making portrait pages on USletter paper (8.5inx11in)
fop -q -fo gpsbabel.fo -pdf gpsbabel.pdf 
make: fop: Command not found
Makefile:267: recipe for target 'gpsbabel.pdf' failed
make: *** [gpsbabel.pdf] Error 127

And as a result of "make doc" my  "./doc/htmldoc-development/" directory
now contains 213 files "*.html", all with identical contents:

<?php
require("../lib/smarty_common.php");
$smarty->display($template);
?>

So apparently I'm requiring Smarty  (as well as PHP)  to be able to make
the HTML documentation,  together with "fop" to make the PDF documentat-
ion.   What other software prerequisites   will I find documented in the
documentation when I ever manage to build it? :-)

Wishlist:

1. "./configure"  should find out  whether or not  Smarty,  PHP,  "fop",
   "xmlwf", "xmllint", and "xsltproc"  (and maybe even Perl)  are avail-
   able at all and should create Perl script "xmldoc/makedoc" or an add-
   itional Shell script in  such a way that  it complains  about missing
   software in advance and if applicable, points out to use new make re-
   cipies "make doc-html" or "make doc-pdf" directly to get the same am-
   ount of documentation but less error messages.  Regarding "fop" there
   are already some such comments in file "Makefile" which could be used
   as a start (but these comments also show how fragile making this doc-
   umentation currently is).

2. "make  doc" should at  least  create or  provide traditional Unix man
   pages readable with "man"  (these are  creatable,  for instance, with
   "DocBook" (which you seem to use anyway) and could already be includ-
   ed in the source repository).

3. Making the documentation should not depend on a plethora of different
   utilities which only cooperate when specific version requirements are
   met.   Documentation can well  be more advanced  than the ancient and
   perhaps spartanic "troff" man pages,  but ideally the software requi-
   rements for creating the documentation should only consist of a sing-
   le documentation package  plus the interpreter  it is written in (for
   instance "docutils", which requires Python but nothing else).

4. Both, making and  reading the documentation  should not  depend on an
   Internet connection but should be possible offline.

Well, I'm aware it's not Christmas time, so these wishes will not be met
anytime soon, but as a user of a software  providing as complex features
as GPSBabel does, I feel a bit lost without documentation which is both,
up to date and offline.

Sincerely,
  Rainer

 ----------------------------------------------------------------------
| Rainer M Woitok                | Phone : (+49 60 93) 487 95 95       |
| Kolpingstraße 3                | Mobile: (+49 172) 813 6 831         |
| D-63846 Laufach                | Mail  : [hidden email]     |
| Germany                        |                                     |
 ----------------------------------------------------------------------

------------------------------------------------------------------------------
_______________________________________________
Gpsbabel-misc mailing list http://www.gpsbabel.org
[hidden email]
To unsubscribe, change list options, or see archives, visit:
https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc


------------------------------------------------------------------------------

_______________________________________________
Gpsbabel-misc mailing list http://www.gpsbabel.org
[hidden email]
To unsubscribe, change list options, or see archives, visit:
https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc
Reply | Threaded
Open this post in threaded view
|

Re: New repository, "make doc"

Dr Rainer Woitok
Steve,

On Wednesday, 2015-08-19 17:15:57 -0600, you wrote:

> ...
> https://github.com/gpsbabel/gpsbabel/blob/master/.travis.yml
> ...
> https://github.com/gpsbabel/gpsbabel/blob/master/gpsbabel/build_and_test
> ...
> https://travis-ci.org/gpsbabel/gpsbabel

This all doesn't really help me in that it doesn't cause "make doc" to
succeed locally on my laptop under Cygwin.

> ...
>    o Entire Manual as PDF

Wow!  That's the only idea that really helps me :-)

So I've now created the following local patch:

--- a/Makefile.in
+++ b/Makefile.in
@@ -288,7 +288,7 @@
        wget -O $(WEB)/changes.html http://www.gpsbabel.org/changes.html || exit 1
        rm -f $(WEB)/changes.html.1 > /dev/null
 
-doc: gpsbabel $(WEB)/htmldoc-$(DOCVERSION)/index.html gpsbabel.pdf # readme.txt
+doc: ; wget -O $(WEB)/gpsbabel.pdf http://www.gpsbabel.org/htmldoc-development/gpsbabel.pdf
 
 FORCE:
----------- End of Patch -----------

which is only to be applied locally here and which MUST NEVER EVER MAKE
IT INTO THE SOURCE REPOSITORY at Github.Com! :-)

That's probably  really the easiest way for me  to keep my GPSBabel doc-
umentation up to date,  provided you or Robert really  run "make doc" on
GPSBabel.Org whenever there are any  documentation updates in the source
repository.

Thanks for the great idea!

Sincerely,
  Rainer

 ----------------------------------------------------------------------
| Rainer M Woitok                | Phone : (+49 60 93) 487 95 95       |
| Kolpingstraße 3                | Mobile: (+49 172) 813 6 831         |
| D-63846 Laufach                | Mail  : [hidden email]     |
| Germany                        |                                     |
 ----------------------------------------------------------------------

------------------------------------------------------------------------------
_______________________________________________
Gpsbabel-misc mailing list http://www.gpsbabel.org
[hidden email]
To unsubscribe, change list options, or see archives, visit:
https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc
Reply | Threaded
Open this post in threaded view
|

Re: New repository, "make doc"

Robert Lipe-4
Steven is, as usual, correct.

Our 'doc' target is perhaps misnamed as it really is useful only if you happen to be me.  It requires a lot of finicky tools, many of which don't work well offline.  It's not really so much a 'doc' target as "build me a directory of stuff that Robert can push to gpsbabel.org."  Until about a year ago, it build a pile of HTML pages that separate scripts would then run over to "fix" page titles, add page navigation, footers, headers, and such.  About a year ago, I changed gpsbabel.org to use the Smarty templating system so now Smarty does that.  That means there's a smarty tree (which, you learned, is boilerplate and relies on some clever PHP) that reads the (seriously unattractive) HTML output from docbook.  Worse still, we use Perl to preprocess the XML that gets fed to docbook to provide the "This format can read and write..." and stitch the options to the formats and filters.  Similarly, the http://www.gpsbabel.org/capabilities.html page is largely machine generated from all this. Having the 'doc' target in the postsubmit isn't as much about publishing an updated version of that doc as about ensuring that we've not broken or omitted the doc.

The upside of all of this is that when a dev adds a new format, one file in a reasonably readable (even if only by example) XML format, gets doc for that format added to the web site, complete with working index and next and previous links.  Similarly, deleting a format (or even just turning it off in the Makefile) cleans up those links.

This is all rather distracting stuff if you just want the doc offline.  The PDF is a reasonable tradeoff, though it does contain some formatting issues that are below my radar.  Our doc is pretty slow-moving.  We (hopefully) add pages as we add formats and filters and options.  We sometimes improve what's there to better explain things, fix decayed links, or make them match reality, but the delta between -development and the last release is rarely very interesting to a typical user.   We're nearly a 15 year old project; most of our words don't change between releases. 

On Fri, Aug 21, 2015 at 6:51 AM, Dr Rainer Woitok <[hidden email]> wrote:
Steve,

On Wednesday, 2015-08-19 17:15:57 -0600, you wrote:

> ...
> https://github.com/gpsbabel/gpsbabel/blob/master/.travis.yml
> ...
> https://github.com/gpsbabel/gpsbabel/blob/master/gpsbabel/build_and_test
> ...
> https://travis-ci.org/gpsbabel/gpsbabel

This all doesn't really help me in that it doesn't cause "make doc" to
succeed locally on my laptop under Cygwin.

> ...
>    o Entire Manual as PDF

Wow!  That's the only idea that really helps me :-)

So I've now created the following local patch:

--- a/Makefile.in
+++ b/Makefile.in
@@ -288,7 +288,7 @@
        wget -O $(WEB)/changes.html http://www.gpsbabel.org/changes.html || exit 1
        rm -f $(WEB)/changes.html.1 > /dev/null

-doc: gpsbabel $(WEB)/htmldoc-$(DOCVERSION)/index.html gpsbabel.pdf # readme.txt
+doc: ; wget -O $(WEB)/gpsbabel.pdf http://www.gpsbabel.org/htmldoc-development/gpsbabel.pdf

 FORCE:
----------- End of Patch -----------

which is only to be applied locally here and which MUST NEVER EVER MAKE
IT INTO THE SOURCE REPOSITORY at Github.Com! :-)

That's probably  really the easiest way for me  to keep my GPSBabel doc-
umentation up to date,  provided you or Robert really  run "make doc" on
GPSBabel.Org whenever there are any  documentation updates in the source
repository.

Thanks for the great idea!

Sincerely,
  Rainer

 ----------------------------------------------------------------------
| Rainer M Woitok                | Phone : <a href="tel:%28%2B49%2060%2093%29%20487%2095%2095" value="+4960934879595">(+49 60 93) 487 95 95       |
| Kolpingstraße 3                | Mobile: <a href="tel:%28%2B49%20172%29%20813%206%20831" value="+491728136831">(+49 172) 813 6 831         |
| D-63846 Laufach                | Mail  : [hidden email]     |
| Germany                        |                                     |
 ----------------------------------------------------------------------

------------------------------------------------------------------------------
_______________________________________________
Gpsbabel-misc mailing list http://www.gpsbabel.org
[hidden email]
To unsubscribe, change list options, or see archives, visit:
https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc


------------------------------------------------------------------------------

_______________________________________________
Gpsbabel-misc mailing list http://www.gpsbabel.org
[hidden email]
To unsubscribe, change list options, or see archives, visit:
https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc