[Doc-SIG] proposal: a process for solving the Python Documentation Problem

[Bill Janssen]

> The document parser people find that there are some times when plain
> text is not enough, and you really need to include some markup somewhere.
> If they stick it in the document, they have started down the road where
> they make their input text easier to parse.  You can end up with
> markup-gloop this way too, even if it is only structural markup you
> are inserting.  If you stick it in a companion document, then the
> two get out of sync, and somebody always loses one.

Some of the original document formats developed at PARC in the 70's
for use on the Alto and Dorado computers used plain text plus markup.
There was a plain-text body, followed by a zero octet (or perhaps two,
I don't remember), followed by a binary section that included the
markup.  Most text processors of the time would simply trim off the
binary section when presenting the document, so what you saw in a text
editor was just the plain text.  WYSIWYG document editors, however,
would also read the markup and interpret it appropriately for editing
purposes.  The two didn't get out-of-sync because they were in the
same file.

Bill