Ahoy, Fellow Dockers!
To increase the maintainability of the document build process, the
Steering Committee has decided to make a significant change to the
Makefile's used to construct each document. A new file
"docs-common/Makefile.common" has been created and _all_ of the
default make(1) targets and rules have been moved to that file.
Now, a document's local Makefile is very short and only needs to
define some boilerplate macros, plus the all-important DOCNAME macro.
Armed with this information, and including the
"../docs-common/Makefile.common" file, you will be ready to generate
HTML's, PDF's, tarballs, and however else it is decided to package
our documents.
To see this in action, update your "docs-common" directory and then
look at the "Makefile" in the "example-tutorial" project.
I hope this change will insulate the individual document files from
future mangling as we add new capabilities.
Technical note #1:
Since all the make targets defined in "Makefile.common" use
double-colon (::) definitions, adding any additional steps needed for
an unusual document is easy. In your local "Makefile", add your own
target, such as "${DOCNAME}/index.html::" followed by your own rules.
For an example, again look at the example tutorial.
Technical note #2:
In the local "Makefile", the XMLFILE macro still references the main
XML file for your document -- the file that contains the DOCTYPE
declaration. If your document includes any external files, just list
their names in the XMLEXTRAFILES macro so the dependencies will all
work out.
As always, if you have questions, feel free to submit them to this
list and I'll explain or apologize as necessary ;-)
Tommy