One page document of as

[Jose E. Marchesi]

> On 26 Apr 2021 11:43, Nick Clifton via Binutils wrote:
>> > can do, but how does that fit into the on-going release process ?  is there a
>> > script someone runs to generate all of these, and then upload specific files ?
>> 
>> At the moment when I create a release I follow the steps outlined in 
>> binutils/README-how-to-make-a-release.  Which basically involves 
>> manually creating the documentation and uploading it.
>
> wdyt of this ?  we'd need this patch in all the major dirs
> (bfd/etc...).

An alternative would be to use the gendocs.sh script from gnulib with
rules like the following:

.PHONY: web-manual
web-manual:
	$(AM_V_GEN)test -z "$(manual_title)" \
	  && { echo define manual_title in cfg.mk 1>&2; exit 1; } || :
	$(AM_V_at)cd '$(srcdir)/doc'; \
	  $(SHELL) gendocs.sh $(gendocs_options_) \
	     -o '$(abs_builddir)/doc/manual' \
	     --email $(PACKAGE_BUGREPORT) $(PACKAGE) \
	    "$(PACKAGE_NAME) - $(manual_title)"
	$(AM_V_at)echo " *** Upload the doc/manual directory to web-cvs."

There is a GNU standard template to use with gendocs.sh:
https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template

The script generates the full usual assortment of formats: HTML on a
single page, splitted HTML, PDF, PS, info, the source .texi, etc.

And the output looks like this:
https://www.gnu.org/software/coreutils/manual/

This is another example of the output, using a customized template:
https://jemarch.net/poke-1.2-manual/

There is also a little build-aux/gnu-web-doc-update script in gnulib
that simplifies updating the web documentation at
https://www.gnu.org/software/PACKAGE/manual/.  It can be used with a
rule like:

.PHONY: web-manual-update
web-manual-update:
	$(AM_V_GEN)cd $(srcdir) \
	  && gnu-web-doc-update -C $(abs_builddir)

Note that we don't need to integrate with gnulib-tool in order to use
these scripts: we could just copy them over.

Properly integrating binutils with gnulib would be better, but that is
for another project I guess... :)