In the past, we have hit annoying incompatibilities when
people have attempted to rebuild ELinks documentation
with new versions of AsciiDoc:
http://bugzilla.elinks.cz/show_bug.cgi?id=989http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=491820
So now we bundle the configuration files from a known good version
to let ELinks documentation be built with them regardless of which
version has been installed on the machine.
The intention is to convert --config-help and --long-help outputs to
DocBook XML and XHTML rather than AsciiDoc, so that the converter does
not have to work around the intricate AsciiDoc syntax. However, this
commit does not yet connect the script to doc/Makefile.
XHTML could be generated from DocBook XML, but the script outputs it
directly because our DocBook is primarily intended for manual pages
and so does not have all the links that are useful in HTML.
This version takes about 1/300 of the time of the shell version
and fixes several errors in the output, most importantly that
option descriptions were being truncated at the first empty line.
Because help2doc is run only from make update-man, and the distributed
tarballs include prebuilt man pages, people building ELinks need not
have Perl installed.
This changes the init target to be idempotent: most importantly it will now
never overwrite a Makefile if it exists. Additionally 'make init' will
generate the .vimrc files. Yay, no more stupid 'added fairies' commits! ;)
This simplifies help2doc since it now just have to do one single thing with
output of either --config-help or --long-help. The new manpage is not as
fancy wrt. indentation and sub titles but it is more uniform and we get a
HTML version.
Generate options-{config,command}.txt with help2doc. Only conditionally
check for API header files, to speed up execusion.
You can now use: make {all-docs,pdf,html,man,api,update-man}
instead of: make {all-docs,pdf-docs,html-docs,man-docs}
Away is building into separate dirs. This makes make able to actually get
dependencies right, since there are now a collection of 'common' build
rules, some of which have even been moved to use the cmd infrastructure.
To update the man pages there is a new update-man rule. It builds the
manual pages and copies them to their proper place under man/ while doing
the final preformatting.
As good thing is that the (two) man pages are moved to .txt files and
include the generated content.
The API building thing is also refined. It builds into api/ and builds it's
list of files dynamically by searching throught the .h files in the src/
directory. Documented header files must contain a comment like this:
/* API Doc :: <api-name> */
where <api-name> is the name used for the file under api/, for example
dom-scanner.
