Graydon Saunders | 12 Dec 17:16 2003

building documents from multiple files

I have a bunch of restructured text content files which get collected
via a couple layers of files with nothing in them but headings and
include directives to build documentation.   (All the content is in the
leaves of the tree.)

The top level such 'includes' file also includes a 'glossary' file and a
'detailed reference' file; the other documentation refers to these files
pretty indiscriminately.  (so `widget`_ shows up in the text a lot; if
the reader wants a reminder of what a widget is, they can click on it
and wind up in the glossary or the detailed reference where _`widget` is
defined.)

The main documentation has now grown to a size where having it all in
one file is unwieldy and awkward.

I would like to be able to break the main documentation up, so that
instead of one top level file full of include directives, I can have
four or five sections which build independently.  What I don't know how
to do is how I can keep the common glossary and detailed references
without including it in each section.

So what I've got is:

Top Level
:::::::::

.. include:: section_one.txt
.. include:: section_two.txt
.. include:: section_three.txt

(Continue reading)

David Goodger | 12 Dec 17:33 2003

Re: building documents from multiple files

For everyone's benefit (I already told Graydon), there are some
existing notes on the subject:
<http://docutils.sf.net/spec/notes.html#large-documents>.  Follow
the links in the first paragraph for other relevant notes.

-- David Goodger

-------------------------------------------------------
This SF.net email is sponsored by: IBM Linux Tutorials.
Become an expert in LINUX or just sharpen your skills.  Sign up for IBM's
Free Linux Tutorials.  Learn everything from the bash shell to sys admin.
Click now! http://ads.osdn.com/?ad_id=1278&alloc_id=3371&op=click

Gmane