www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - DDoc enhancements?

reply Derek Parnell <derek psych.ward> writes:
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
Sep 20 2005
next sibling parent reply "Walter Bright" <newshound digitalmars.com> writes:
Those are both good suggestions.
Sep 20 2005
parent reply Hasan Aljudy <hasan.aljudy gmail.com> writes:
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?
Sep 22 2005
next sibling parent "Walter Bright" <newshound digitalmars.com> writes:
"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.
Sep 22 2005
prev sibling parent reply Derek Parnell <derek psych.ward> writes:
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
Sep 22 2005
parent James Dunne <james.jdunne gmail.com> writes:
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.
Sep 23 2005
prev sibling parent "Uwe Salomon" <post uwesalomon.de> writes:
 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
Sep 20 2005