[ANN] docs-common/Makefile.common

[Tommy Reynolds]

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

[James Laska]

Great work on the Makefile.common ... are there plans to add
html-nochunks generation?

Thanks,
James Laska

On Tue, 2005-06-28 at 21:28 -0500, Tommy Reynolds wrote:
> 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
>
> fedora-docs-list mailing list
> [e-mail]
> To unsubscribe: 
> http://www.redhat.com/mailman/listinfo/fedora-docs-list

[Tommy Reynolds]

Uttered James Laska , spake thus:
> Great work on the Makefile.common ... are there plans to add
> html-nochunks generation?

I'll look into it.

Cheers

[Paul W. Frields]

On Wed, 2005-06-29 at 09:53 -0400, James Laska wrote:
> Great work on the Makefile.common ... are there plans to add
> html-nochunks generation?

I made a few changes to the Makefile.common, and I think that should
work now.  The example-tutorial/Makefile has been updated as well.

[Tommy Reynolds]

Uttered "Paul W. Frields" , spake thus:
> On Wed, 2005-06-29 at 09:53 -0400, James Laska wrote:
> > Great work on the Makefile.common ... are there plans to add
> > html-nochunks generation?
>
> I made a few changes to the Makefile.common, and I think that should
> work now.  The example-tutorial/Makefile has been updated as well.

Now that's service!  Can I send you a 15% tip?

Cheers

[Tommy Reynolds]

Uttered "Paul W. Frields" , spake thus:
> I made a few changes to the Makefile.common, and I think that should
> work now.  The example-tutorial/Makefile has been updated as well.

Paul,

For "nochunks", where do the graphics and images go?

Cheers

[Paul W. Frields]

On Wed, 2005-06-29 at 09:32 -0500, Tommy Reynolds wrote:
> Uttered "Paul W. Frields" , spake thus:
> > I made a few changes to the Makefile.common, and I think that should
> > work now.  The example-tutorial/Makefile has been updated as well.
>
> Paul,
>
> For "nochunks", where do the graphics and images go?

Whoops.  Well, originally I was thinking to myself, "Self, maybe you
should just leave that stuff out since it makes for, uh, more than one
file."  Then I thought better of it... now the images and CSS come into
the current directory where they're expected.  I don't see a big value
in a "nochunks-tarball," but if you disagree there's no reason we
couldn't have that target.

[Tommy Reynolds]

Uttered "Paul W. Frields" , spake thus:
> > For "nochunks", where do the graphics and images go?
>
> Whoops.  Well, originally I was thinking to myself, "Self, maybe you
> should just leave that stuff out since it makes for, uh, more than one
> file."  Then I thought better of it... now the images and CSS come into
> the current directory where they're expected.  I don't see a big value
> in a "nochunks-tarball," but if you disagree there's no reason we
> couldn't have that target.

Crap, now you've planted a seed and someone will want this feature
;-)

Naw, I wouldn't bother making a no-chunk tarball target unless someone
wanted to make my next house payment.

Good, quick, work!

[Paul W. Frields]

On Wed, 2005-06-29 at 10:43 -0400, Paul W. Frields wrote:
> On Wed, 2005-06-29 at 09:32 -0500, Tommy Reynolds wrote:
> > Uttered "Paul W. Frields" , spake thus:
> > > I made a few changes to the Makefile.common, and I think that should
> > > work now.  The example-tutorial/Makefile has been updated as well.
> >
> > For "nochunks", where do the graphics and images go?
>
> Whoops.  Well, originally I was thinking to myself, "Self, maybe you
> should just leave that stuff out since it makes for, uh, more than one
> file."  Then I thought better of it... now the images and CSS come into
> the current directory where they're expected.  I don't see a big value
> in a "nochunks-tarball," but if you disagree there's no reason we
> couldn't have that target.

By the way, the XSL has been fixed to embed the legalnotice in the
nochunks version rather than creating an outboard file.  While someone
shipping a document without images or CSS doesn't "break" the document
per se, if it goes without the legalnotice intact, that could be
considered an actual problem.

[Karsten Wade]

On Wed, 2005-06-29 at 10:54 -0400, Paul W. Frields wrote:
> By the way, the XSL has been fixed to embed the legalnotice in the
> nochunks version rather than creating an outboard file.  While someone
> shipping a document without images or CSS doesn't "break" the document
> per se, if it goes without the legalnotice intact, that could be
> considered an actual problem.

I'll have to get this into the example-tutorial (perhaps a no-chunks
version?), but the legalnotice appearing at the top of a no-chunks is
why I created all the weirdness around how the legalnotice is used.

legalnotice-en.xml calls in legalnotice-content-en.xml

If you use the standard legalnotice-en.xml and no-chunks, the entire
notice is displayed at the very top of the document above the table of
contents.

The alternative is to use (a version of?) legalnotice-relnotes-en.xml.
This file references an <appendix> that contains the full text, as is
common with source code and others -- you don't include a copy of the
GPL in the header of every file, you refer to LICENSE.

Then you make an <appendix> and use that to pull in legalnotice-content-
en.xml.

[Tommy Reynolds]

Uttered Karsten Wade , spake thus:
> Then you make an <appendix> and use that to pull in legalnotice-content-
> en.xml.

I'm a little concerned over the idea of using an appendix.  On the
government contracts I've worked on, any material in an appendix is
not legally (at least, not contractually) part of that document.
I've never seen any document with a legal notice in an appendix --
only as front matter.  Can we get a webink on this?

Cheers

[Karsten Wade]

On Wed, 2005-06-29 at 21:02 -0500, Tommy Reynolds wrote:
> Uttered Karsten Wade , spake thus:
> > Then you make an <appendix> and use that to pull in legalnotice-content-
> > en.xml.
>
> I'm a little concerned over the idea of using an appendix.  On the
> government contracts I've worked on, any material in an appendix is
> not legally (at least, not contractually) part of that document.
> I've never seen any document with a legal notice in an appendix --
> only as front matter.  Can we get a webink on this?

We could, but it would be easier if we solved it ourselves.

This is probably best handled in XSL, the solution being to move the
legalnotice to appear after the ToC in no-chunks.  Or is that front
enough?

How do your concerns relate to usage of the GPL, the LICENSE document,
and source code?

If not an appendix, how about a first or final <section>?

- Karsten

[Tommy Reynolds]

Uttered Karsten Wade , spake thus:
> This is probably best handled in XSL, the solution being to move the
> legalnotice to appear after the ToC in no-chunks.  Or is that front
> enough?

I think immediately after the ToC would be ideal.  Nobody reads that
anyway ;-)

Cheers

[Paul W. Frields]

On Wed, 2005-06-29 at 18:16 -0700, Karsten Wade wrote:
> On Wed, 2005-06-29 at 10:54 -0400, Paul W. Frields wrote:
> > By the way, the XSL has been fixed to embed the legalnotice in the
> > nochunks version rather than creating an outboard file.  While someone
> > shipping a document without images or CSS doesn't "break" the document
> > per se, if it goes without the legalnotice intact, that could be
> > considered an actual problem.
>
> I'll have to get this into the example-tutorial (perhaps a no-chunks
> version?), but the legalnotice appearing at the top of a no-chunks is
> why I created all the weirdness around how the legalnotice is used.
>
> legalnotice-en.xml calls in legalnotice-content-en.xml
>
> If you use the standard legalnotice-en.xml and no-chunks, the entire
> notice is displayed at the very top of the document above the table of
> contents.

Hmm, I tested the nochunking on my system before I made any XSL changes,
and the legal notice still built as an added file in ./${DOCNAME} .  Can
you explain how the system is supposed to work for XSL(T) idiots so that
I can understand where I went wrong?  Sorry if I've goofed this up; here
are the revisions in case someone wants to see what regression I caused.

html-common.xsl: 1.8 -> 1.9
main-html.xsl: 1.4 -> 1.5
main-html-nochunks: 1.1 -> 1.2

On my local copy of the repository, I reverted these XSL files, to see
if I could reproduce the behavior.  Using the current
docs-common/Makefile.common, 'make html-nochunks' indeed breaks the
legalnotice off to a separate file.  With my changes of yesterday
restored, it works correctly, embedding the legalnotice in the
$DOCNAME.html file.

Any guidance would be appreciated, especially if it helps me understand
this XSL stuff better.