Re: [Docutils-users] Include and title

[G. M. <mi...@us...>]

On 25.06.08, Guillaume Bouchard wrote:

> I have to write a large document in ReST with many person, the idea is
> that everyone write is document (which can be a whole level 2 section,
> or just small parts of a level 4 section) in a file, and at the end I
> have to pack all the file together.

> First Idea, use the include directive. Or the problem with it is that I
> MUST coordinate the section title adornments for the whole team.

> 1) It's not easy
> 2) It's not safe
> 3) I especially enjoy when I did not say to my coworkers that they are
> using a special language. If I told them about title, I must told them
> about ReST.


> Now I have two solutions:

> 1) write a regex based quick hack that convert the file
> 2) write a new directive ..include_with_depth which can take an argument
> which is the title level of the first title reach in the included file
...
> Is there a way I miss ?

0) Tell your co-workers that it is a style requirement to have consistent
   title adornments and state them (in a template or as a list).
   Easy, not save, no need to tell about ReST.
   
3) Let the co-workers use a ReST supporting editor (e.g. Emacs, or Jed_).

   Easy, save, will not work without telling about ReST.
   
4) Use the "normalize_headings" function of Jed's `rst-mode`_ to 
   convert a valid section hierarchy to a common norm.
   
   This could replace 1) with a ready converter.
   If you are going for this route, I'll provide more details on request.

Günter
   
.. _Jed: http://www.jedsoft.org/jed/   
.. _rst-mode: http://jedmodes.sf.net/mode/rst/