Re: ✘asciidoc vs asciidoctor, issue #118

[Greg Troxel]

"Gary E. Miller" <gem@rellim.com> writes:

>> 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.

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.

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.

  -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

I also see missing docbuild steps:

  -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.

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.


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.

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.


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

signature.asc
Description: PGP signature