[Doc-SIG] Re: Ease of use is #1
Moshe Zadka <email@example.com>
Mon, 7 Feb 2000 07:13:00 +0200 (IST)
On Sun, 6 Feb 2000, Ka-Ping Yee wrote:
> Before i begin, let me make an attempt to propose the two most important
> goals of any documentation project.
> I. To encourage people to write lots of documentation.
> II. To make that documentation as accessible as possible.
> The attached file is an example; it is discussed in more detail below.
> On Fri, 4 Feb 2000, Moshe Zadka wrote:
> > Special tokens:
> > @ -- escapes any character following it (i.e., @c is always translated
> > to c)
> > [ -- a short tag opener. Closed with a matching ]
> > ::(newline) -- beginning a a long tag. everything until the
> > indent level returns to that of the line which started the long
> > tag is part of the contents.
> > (newline)(newline) -- new paragraph.
> > The syntax of short tags is '[' tagname ' ' contents ']' where contents is
> > any valid snippet of docstring, with the exception of a long tag.
> > The syntax of long tags is
> > tagname (attr '=' value)*'::'
> > contents
> [there follow some 450 lines of description]
No, 10 lines of description and 450 lines of a module done up in the way I
Ping, it seems you didn't even read my message.
While I admire the way you markup by "guessing", I must admit I have my
qualms about this approach: too little control for the documenter.
Possibly, a mix of the two approaches is in order.