[Doc-SIG] Re: [Tutor] Documentation concerns.

[Beni Cherniavsky]

Ian Bicking wrote on 2003-05-26:

> On Mon, 2003-05-26 at 04:44, Beni Cherniavsky wrote:
> > Having all info inside the document itself is better because when
> > editing you can see it all.  If the docstrings are included later, you
> > might not notice when they change and the documentation can get out of
> > sync.  Even if the docstrings and the exrnal doc don't conradict each
> > other, it's harder to ensure that they cover all material without gaps
> > or too much overlap.  Of course, it's good practice to render the
> > final documentation and read it from time to time but you woulnd't do
> > it every 2 minutes, right?
> >
> > I think the best solution is to have a tool that includes the
> > docstrings into your source while leaving some markers around it, so
> > that it is idempotent when run upon its own output.  Then you can
> > directly edit this output like it would appear at the end but you can
> > sync it to the docstrings at any moment by re-running the tool.
>
> Like maybe, say:
>
> .. inline Foo
>
> (stuff taken from Foo's docstring)
>
> .. end inline
>
> And instead of making this a directive, it is a pre-compiler, where
> everything between ".. inline Foo" and ".. end inline" is derivative
> (and so shouldn't be edited, but can be read).
>
Yes, more or less so.

> Of course, it should support more than just inlining docstrings, as
> there's already two other examples of inlining that we want to use, and
> no doubt more are likely.
>
Of course.  This is relevant to any kind of inlining mechanism.

> But it is a little crude to use a preprocessor.  That seems integral,
> though, without some sort of powerful IDE that dynamically inlined such
> documentation.
>
Emacs, with a key bound to filtering the region through it?  And/or a
makefile target to update all files?  The point is to make the
preprocessor safe and idempotent and then have it work in-place
instead of the classical approach of separate source and generated
files.

For extra polish it seems to make sense to omit the inlined texts in
cvs.  OTOH, then cvs will not detect conflicts between the narrative
and the inlined texts.

-- 
Beni Cherniavsky <cben@users.sf.net>

The Three Laws of Copy-Protechnics:
http://www.technion.ac.il/~cben/threelaws.html