"anderson" <anderson@firestar.com.au> wrote in news:al7dgi$2nua$1@digitaldaemon.com:

> It would be nice if the docgen produced pages into separt folders depending on the package which they reside, optionally or a zip file. That's more a docgen compiler thing then a spec thing.
> 

I think initialy in two compilers:

1. A stripper    	:-)
2. A indexer
3. A formatter

The stripper extracts the documentation and generate a new file by each
source file parsed. This file must be a xml docbook, but a best format can
be discussed.
The indexer take a lot of these files and generate the indexes, glossaries
and categories and a sample docbook book index file.
The user can now compile the documentation in his preferred format using
his preferred docbook toolset.
The formater simply will help the user putting empty comments in
declarations.

The first two compilers need to be a part of specification ( maybe v15 :-)).

I have thinked about a form of parametrizing the preferences like :

o    	I dont wanna variable in documentation.
o    	I dont wanna declarations without comment in documentation.
o    	I wanna the oposite...

What you think about all?

"anderson" <anderson@firestar.com.au> wrote in news:al7dgi$2nua$1 @digitaldaemon.com:

> copyrigth ?? -> copyright

copyrigth , lenght, widht, heigth, ligth !

I newer write this correctly !!! Portuguese is much more simple !!! :-)

Jason Mills <jmills@cs.mun.ca> wrote in news:al7edl$2pih$1 @digitaldaemon.com:

> Can we use single line comments in place of the /** **/ style comments, as shown below:
> 
> 
>    ///
>    /// author: Wolfrang Amadeus Mozart <wam@music.org>
>    ///
>    /// This class plays a sinfonie of Mozart. It can be used for learning
>    /// music or for learning D documentation
>    ///
>    class sinfonie{
>    ...
>    }
> 
> 

I think it's ugly. But I think is valid.
These are also:

 /**
   * author: Wolfrang Amadeus Mozart <wam@music.org>
  **/
 /**
   * This class plays a sinfonie of Mozart. It can be used for learning
   * music or for learning D documentation
  **/
   class sinfonie{
   ...
   }

The rule I have thinked is the comment, if are in a body (not between { } ) is attached to next declaration.

What this looks in your eyes ?

Pavel Minayev <evilone@omen.ru> wrote in news:al7oem$8d7$1 @digitaldaemon.com:

> So that the doc generator knows which line is commented (next or previous). It's doxygen syntax.
> 

Yes. Maybe the easiest form of making a compiler for documentation will be writing a extension for doxygen.

I'm a bad speller myself, and I can't blame a second language :) I don't mind if someone corrects me (not implying that you don't). One thing though, "copyright" is something that a spell checker should pickup so it's even less of a small deal.

"Juarez Rudsatz" <juarez@nowhere.com> wrote in message news:Xns9280BF864E127juarezcom@63.105.9.61...
> "anderson" <anderson@firestar.com.au> wrote in news:al7dgi$2nua$1 @digitaldaemon.com:
>
> > copyrigth ?? -> copyright
>
> copyrigth , lenght, widht, heigth, ligth !
>
> I newer write this correctly !!!
> Portuguese is much more simple !!! :-)

>>Can we use single line comments in place of the /** **/ style comments,
>>as shown below:
>>
>>
>>   ///
>>   /// author: Wolfrang Amadeus Mozart <wam@music.org>
>>   ///
>>   /// This class plays a sinfonie of Mozart. It can be used for learning
>>   /// music or for learning D documentation
>>   ///
>>   class sinfonie{
>>   ...
>>   }
>>
>>
> 
> 
> I think it's ugly. But I think is valid.

I (and some of my co-workers) like using /// as above.

> These are also:
> 
>  /**    * author: Wolfrang Amadeus Mozart <wam@music.org>
>   **/
>  /**    * This class plays a sinfonie of Mozart. It can be used for learning
>    * music or for learning D documentation
>   **/
>    class sinfonie{
>    ...
>    }
> 
> The rule I have thinked is the comment, if are in a body (not between { } )
> is attached to next declaration.
> 
> What this looks in your eyes ?

This *looks* like two seperate comments, but I guess it could be treated as one.

Juarez Rudsatz wrote:
> Pavel Minayev <evilone@omen.ru> wrote in news:al7oem$8d7$1
> @digitaldaemon.com:
> 
> 
>>So that the doc generator knows which line is commented (next or previous). It's doxygen syntax.
>>
> 
> 
> Yes. Maybe the easiest form of making a compiler for documentation will be writing a extension for doxygen.

I have used doxygen for some C++ documentation, it's great. Maybe the
easiest (best) solution to standard D source code documentation is to
adopt doxygen style comments, i.e. use the doxygen spec and write an
extension for doxygen as you suggested. A programmer could than use the
same style comments for D, C++, and Java (and other languages doxygen
supports).

Jason

Mac Reiter <Mac_member@pathlink.com> wrote in news:al6380$2uv9$1@digitaldaemon.com:

> Nested numbered lists will have a problem with the following:
> 
> #1 Top list, item 1
> #2 Top list, item 2
> #1 Nest list, item 1
> #2 Nest list, item 2
> #3 Which list?, item 3
> 
> If indentation is a controlling mechanism, it needs to be documented as such.

No identation is not a good method of controling lists or any documentation structure, IMHO. However you could use it for better looking in the source code.

I have thinked in this rules:

1. On Unordered lists changing the bullet (+-o) define a child list 2. On Ordered lists changing the sequence number define a child list

So, tha above code could be rendered in html as :

<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2</li>
    	    	<li>Which list?, item 3</li>
    	</ol>
</ol>

> It might be better to take the list ending blank line and also use it for sublists:
> 
> #1 Top list, item 1
> #2 Top list, item 2
> #1 Nest list, item 1
> #2 Nest list, item 2
> 
> #3 Top list, item 3

The number #3 does not reflect, necessarily, the initial values. Doing this will increase the rules for implemantation and does not look nice.

<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2</li>
    	</ol>
</ol>
<ol>
    	<li>Top list, item 3</li>
</ol>

> Of course, this just delays the inevitable:
> 
> #1 Top list, item 1
> #2 Top list, item 2
> #1 Nest list, item 1
> #2 Nest list, item 2
> #1 Deep list, item 1
> #2 Deep list, item 2
> 
> #3 Which list?, item 3

<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2</li>
    	    	<ol>
    	    	    	<li>Deep list, item 1</li>
    	    	    	<li>Deep list, item 2</li>
    	    	</ol>
    	</ol>
<ol>
    	<li>Which list?, item 3</li>
</ol>

> Two blank lines in a row (the direct extension of my previous
> suggestion) is not particularly obvious when you read it.  It may be
> necessary to make a terminating symbol to end a (sub)list:
> 
> #1 Top list, item 1
> #2 Top list, item 2
> #1 Nest list, item 1
> #2 Nest list, item 2
> #x
> #3 Top list, item 3
> #x

The more simple aproach is consider #x as valid text and this a multi- line issue.

<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2 #x</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2 #x</li>
    	</ol>
</ol>
<ol>
    	<li>Top list, item 3</li>
</ol>

There are no need of list terminators if following the 2 golden rules. Its just polute the visual IMHO.

What you think ? It is consistent ? There are some bug ? Looks nice ?

Saudações

Juarez Rudsatz

Juarez Rudsatz wrote:

> So, tha above code could be rendered in html as :
> 
> <ol>
>     	<li>Top list, item 1</li>
>     	<li>Top list, item 2</li>
>     	<ol>
>     	    	<li>Nest list, item 1</li>
>     	    	<li>Nest list, item 2</li>
>     	    	<li>Which list?, item 3</li>
>     	</ol>
> </ol>

But what if I _want_ the "Which list?" item to be an item #3 in the top list?!

> What you think ? It is consistent ? There are some bug ? Looks nice ?

It seems like you're trying to solve a "dangling else"-like C problem... not aware of any solution better than C one though.

Pavel Minayev <evilone@omen.ru> wrote:
> Juarez Rudsatz wrote:
> 
>> So, tha above code could be rendered in html as :
>> 
>> <ol>
>>       <li>Top list, item 1</li>
>>       <li>Top list, item 2</li>
>>       <ol>
>>               <li>Nest list, item 1</li>
>>               <li>Nest list, item 2</li>
>>               <li>Which list?, item 3</li>
>>       </ol>
>> </ol>
> 
> But what if I _want_ the "Which list?" item to be an item #3 in the top list?!
> 
>> What you think ? It is consistent ? There are some bug ? Looks nice ?
> 
> It seems like you're trying to solve a "dangling else"-like C problem... not aware of any solution better than C one though.

Good obsevation !
But what could be the solution?

1. Requering a empty item what will not render?

#1 list 1, item 1
#1 list 2, item 1
#2
#2 list 1, item 2

2. Use a terminator for lists?

#1 list1, item 1
#1 list2, item 1
#x
#2 list1, item 2

3. Use a empty line as that terminator?

#1 list1, item 1
#1 list2, item 1

#2 list1, item 2

Here continue the text out of list

4. Using a optional different sintax for last item?

#1 list1, item 1
#1# list2, item 1, last item
#2 list1, item 2
#3# list1, item 3, last item
#4 list3, item 1

5. Using tabs, for list level?
#1 list2, item 1
<tab> #1list 2, item 1
#2 list1, item 2
<tab><tab><tab><tab>#1 list level 4, item 1

Any comment?