I like that way one can define new section headers just by using a word followed by a colon. However, can I suggest that you replace single underscores with a space when the output is generated. That way, "Change_log:" with appear as "Change log" which looks better.

I'd also like to suggest an expansion of the macro concept.

If a macro is defined in the format ...

  NAME() = (prefix)(suffix)

then when it is used as ...

  $(NAME some text goes here)

the output will be ...

  prefixsome text goes heresuffix

Note that both 'prefix' and 'suffix' could be empty strings.

This will allow a form of generic and portable output forms. For example...

/*************
    Macros:
      LIST() = (<ul>)(</ul>)
      BOLD() = (<strong>)(</strong>)
      ITALIC() = (<i>)(</i>)
      ITEM() = (<li>)(</li>)
      BREAK =  <br/>
      TITLE() = (<span class=title>)(</span>)
*/

/*************
    Change_Log:
    $(TITLE A list of changes and fixes that have been made.)

    $(BOLD -- $(ITALIC v2.10) -- 30/Sep/2005)
    $(LIST
     $(ITEM ** $(BOLD ENH: )  For Windows environments, command line
           files can now use either "/" or "\" as path separator
           characters.)
     $(ITEM ** $(BOLD ENH: )  The linker program is now used directly
           rather than being invoked via DMD. )
     $(ITEM ** $(BOLD ENH: )  It is now possible to specify compiler
           command line options inside the source code by using a the
           new pragma COMPILE_OPTS. $(BREAK)
           In this case, it will compile the source that contains this
           pragma as a separate step using the supplied options in the
           pragma statement.
      )
    )
***********/

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
20/09/2005 5:10:52 PM

Those are both good suggestions.

> I like that way one can define new section headers just by using a word
> followed by a colon. However, can I suggest that you replace single
> underscores with a space when the output is generated. That way,
> "Change_log:" with appear as "Change log" which looks better.

It would also be possible to accept all input lines of the form "Some text:" as section headers, if they follow an empty line. Thus if a user wants to use a colon in his text, he has to use one of these three ways:

----
Write some text before it is
a possibility, of course:
----
Write some text: behind it is
also ok.
----

If he accidently writes something like this:

----
Prototype is:
----

then he will see the fat section in the output and can simply adjust the input to:

----
Prototype
is:
----

Ciao
uwe

Walter Bright wrote:
> Those are both good suggestions.
> 
> 

Doesn't that defy the point of simplifying the ddoc format and getting rid of things like
@param
and watnot?

"Hasan Aljudy" <hasan.aljudy@gmail.com> wrote in message news:dgum94$1gk5$1@digitaldaemon.com...
> Walter Bright wrote:
> > Those are both good suggestions.
> >
> >
>
> Doesn't that defy the point of simplifying the ddoc format and getting
> rid of things like
> @param
> and watnot?

The idea is that such will be available, but will be entirely unnecessary for most uses.

On Thu, 22 Sep 2005 10:31:37 -0600, Hasan Aljudy wrote:

> Walter Bright wrote:
>> Those are both good suggestions.
>> 
>> 
> 
> Doesn't that defy the point of simplifying the ddoc format and getting
> rid of things like
> @param
> and watnot?

It is possible to simplify things too much, such that they are no longer useful. At the moment, IMO, DDoc is too simple for me to want to use it. It actually causes more work for me than the embedded documentation technique that I currently employ.

-- 
Derek Parnell
Melbourne, Australia
23/09/2005 6:38:14 AM

Derek Parnell wrote:
> On Thu, 22 Sep 2005 10:31:37 -0600, Hasan Aljudy wrote:
> 
> 
>>Walter Bright wrote:
>>
>>>Those are both good suggestions.
>>>
>>>
>>
>>Doesn't that defy the point of simplifying the ddoc format and getting rid of things like
>>@param
>>and watnot?
> 
> 
> It is possible to simplify things too much, such that they are no longer
> useful. At the moment, IMO, DDoc is too simple for me to want to use it. It
> actually causes more work for me than the embedded documentation technique
> that I currently employ.
> 

Maybe you could highlight a set of differences between your own embedded doc technique and DDoc as it stands.