Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

On Thu, Jan 01, 2015 at 12:54:39AM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Thursday, 1 January 2015 at 00:05:10 UTC, Kiith-Sa wrote:
> >DDoc with Markdown
> 
> This is the biggest deal: what people are talking about is actually
> not that different from what ddoc already does!
> 
> If you write:
> 
> /**
>     Something here.
> 
>     Something else here.
> */
> 
> Ddoc ALREADY converts that into:
> 
> $(DDOC_SUMMARY Something here.)
> 
> $(DDOC_DESCRIPTION Something else here.)
> 
> 
> (Which tbh sometimes bugs me, I don't like how "Given: foo" alwas
> turns into a DDOC_SECTION)

Ddoc has this ugly hack where if you want to suppress certain default
behaviours, you stick _ in front of it. For example:

	_Given: x = ...

will output "Given: x = ..." without a section heading, whereas removing
the _ will make "Given" a section heading.

There's also the (undocumented?) behaviour where multi-word headings are
not recognized as such:

	My heading:

	blah blah blah

does not produce a heading for "My heading". However, if you make it a
single word by using _ instead of a space, then it will become a
heading:

	My_heading:

	blah blah blah

the _ gets replaced with a space in the output.

Now I wonder what you'd have to do if you wanted a literal _ in the
heading... or a word in the text... I'm guessing it's time for
$(UNDERSCORE) all over again.


T

-- 
Shin: (n.) A device for finding furniture in the dark.