[Doc-SIG] Re: Ease of use is #1

[Moshe Zadka]

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
propose.

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.