Re: ✘asciidoc vs asciidoctor, issue #118

[Gary E. Miller]

Yo Greg!

On Fri, 05 Feb 2021 15:12:05 -0500
Greg Troxel <gdt@lexort.com> wrote:

> >> Also, scons dist should probably fail if man pages where not
> >> built, so there are no defective distfiles.  (Either that or never
> >> include built man pages in distfiles.)  
> >
> > Done.  Also, if no AsciiDoctor, but have the built man pages (like
> > from the tar ball), they get installed.  
> 
> With asciidoctor (well asciidoctor26) available, full build from git,
> test, making distfile, using that distfile to build a pacakage. all
> works.

Good.

> Then, I removed the asciidoctor package, and commented out the line in
> pkgsrc that says it is needed, and built the gpsd package -- but from
> the distfile I made above.  That succeeded which means it installed
> the same set of man/doc files.

Good.

> Diffing the build outputs, I find things like
> 
>   -Build of man and HTML documentation enabled.
>   +WARNING: AsciiDoctor not found.
>   +WARNING: Some documentation and html will not be built.

Yes, that is true.

>   -manbuild = 1 (default auto): build help in man and HTML formats.
> No/Auto/Yes. +manbuild = 0 (default auto): build help in man and HTML
> formats.  No/Auto/Yes.
> 
>   +Creating 'gpsd-3.22.1~dev/www/hardware-head.html'
>   +chmod -w gpsd-3.22.1~dev/www/hardware-head.html
> 
> but I still see the install lines for the man pages

Yes, the pre-built copies were installed, instead of newly built ones.

> I also see missing docbuild steps:

If you see it, how is it missing?

>   -cd gpsd-3.22.1~dev/www; (cat hardware-head.html &&
> PYTHONIOENCODING=utf-8 /usr/pkg/bin/python3.8 gpscap.py && cat
> hardware-tail.html) > hardware.html -/usr/pkg/bin/asciidoctor26 -b
> manpage -a gpsdweb=https://gpsd.io/ -o gpsd-3.22.1~dev/man/cgps.1
> gpsd-3.22.1~dev/man/cgps.adoc -/usr/pkg/bin/asciidoctor26 -b html5 -d
> manpage -a gpsdweb=https://gpsd.io/ -o gpsd-3.22.1~dev/www/cgps.html
> gpsd-3.22.1~dev/man/cgps.adoc -/usr/pkg/bin/asciidoctor26 -b manpage
> -a gpsdweb=https://gpsd.io/ -o gpsd-3.22.1~dev/man/gegps.1
> gpsd-3.22.1~dev/man/cgps.adoc -/usr/pkg/bin/asciidoctor26 -b html5 -d
> manpage -a gpsdweb=https://gpsd.io/ -o gpsd-3.22.1~dev/www/gegps.html
> gpsd-3.22.1~dev/man/cgps.adoc -/usr/pkg/bin/asciidoctor26 -b manpage
> -a gpsdweb=https://gpsd.io/ -o gpsd-3.22.1~dev/man/gps.1
> gpsd-3.22.1~dev/man/cgps.adoc -/usr/pkg/bin/asciidoctor26 -b html5 -d
> manpage -a gpsdweb=https://gpsd.io/ -o gpsd-3.22.1~dev/www/gps.html
> gpsd-3.22.1~dev/man/cgps.adoc -/usr/pkg/bin/asciidoctor26 -b manpage
> -a gpsdweb=https://gpsd.io/ -o gpsd-3.22.1~dev/man/gps2udp.1
> gpsd-3.22.1~dev/man/gps2udp.adoc -/usr/pkg/bin/asciidoctor26 -b html5
> -d manpage -a gpsdweb=https://gpsd.io/ -o
> gpsd-3.22.1~dev/www/gps2udp.html gpsd-3.22.1~dev/man/gps2udp.adoc
> 
> and this all looks good.  Looks like hardware.html is not installed
> (which is ok, probably, and not about this) -- pkgsrc is not expecting
> it in the filesystem.

It is installed in gpsd-3.22.1~dev/www, as expected.  That is where
the GitLab web pages expect it.  So as intended and as expected.

> So the build/install with no asciidoctor looks correct.  This is nice
> as it means packaging systems can not depend on asciidoctor/ruby and
> use the distfile-provided man pages, or they can choose to depend on
> asciidoctor/ruby and rebuild them.  I'm not sure what I want to do for
> pkgsrc, but I see both approaches as reasonable choices.

Good, gpsd is behaving as intended, the pkgsrc is your thing.

> Testing trying to make a distfile w/o asciidoctor, the build step
> complained and worked w/o building man pages, and the tests passed.
> That's good.

Good.

> Trying to do scons dist resulted in output ending in:
> 
>   manbuild = 0 (default auto): build help in man and HTML formats.
> No/Auto/Yes. target_python = /usr/pkg/bin/python3.7 (default python):
> target Python version as command WARNING: ncurses not found, not
> building cgps or gpsmon. Setting python_shebang to
> /usr/pkg/bin/python3.7 scons: done reading SConscript files.
>   scons: Building targets ...
>   scons: *** [gpsd-3.22.1~dev.zip] Source
> `gpsd-3.22.1~dev/man/cgps.1' not found, needed by target
> `gpsd-3.22.1~dev.zip'. scons: building terminated because of errors.
> WARNING: ncurses not found, not building cgps or gpsmon. WARNING:
> gpsplot is missing required runtime module matplotlib WARNING: xgps
> and xgpsspeed are missing runtime dependencies Ensure your PYTHONPATH
> includes /usr/pkg/lib/python3.7/site-packages/ WARNING: AsciiDoctor
> not found. WARNING: Some documentation and html will not be built.
> 
> which seems like an entirely reasonable way to fail.

Agreed.  It can always be better, not sure how yet.

> So all in all things look good to me - thanks for doing this.

Good.  Making packaging easy as possible is important.

RGDS
GARY
---------------------------------------------------------------------------
Gary E. Miller Rellim 109 NW Wilmington Ave., Suite E, Bend, OR 97703
        gem@rellim.com  Tel:+1 541 382 8588

            Veritas liberabit vos. -- Quid est veritas?
    "If you can't measure it, you can't improve it." - Lord Kelvin

pgpT1blNYVEKg.pgp
Description: OpenPGP digital signature