Suppose I want ddoc output to include this line:

--------------
Note: Blah blabbety blah
--------------

But the colon causes "Note" to be considered a section header. Is there a way to escape the ":" so that it's displayed as expected, but doesn't trigger a section?

On Thu, Feb 23, 2017 at 04:04:39PM -0500, Nick Sabalausky (Abscissa) via Digitalmars-d-learn wrote:
> Suppose I want ddoc output to include this line:
> 
> --------------
> Note: Blah blabbety blah
> --------------
> 
> But the colon causes "Note" to be considered a section header. Is there a way to escape the ":" so that it's displayed as expected, but doesn't trigger a section?

Try:

	_Note: Blah blabbety blah

?

Generally, whenever ddoc does something you don't like, sticking an underscore in front of the offending word is often the solution.  (It's sorta like Windows and the 3-finger salute, but I digress. ;-))


T
-- 
Right now I'm having amnesia and deja vu at the same time. I think I've forgotten this before.

On 02/23/2017 01:04 PM, Nick Sabalausky (Abscissa) wrote:
> Suppose I want ddoc output to include this line:
>
> --------------
> Note: Blah blabbety blah
> --------------
>
> But the colon causes "Note" to be considered a section header. Is there
> a way to escape the ":" so that it's displayed as expected, but doesn't
> trigger a section?

DDoc has the following syntax as in "$ should be replaced with $" at

  http://dlang.org/spec/ddoc.html

(None of the following is tested.)

a) Try using the following macro:

    COLON = :

And then use "Note$(COLON) Blah".

b) Perhaps easier:

    COLON = :
    NOTE = Note$(COLON)

Then use "$(NOTE) Blah"

c) Another option:

    NOTE = Note: $0

Then use "$(NOTE Blah)"

Ali

On Thursday, 23 February 2017 at 21:17:33 UTC, H. S. Teoh wrote:
> 	_Note: Blah blabbety blah

Nope.

Ddoc considers [A-Za-z_]+: to be a section header. You can trick it by doing something like

/++
 Note: ass
+/

Yes, the html entity for a space. That trick's ddoc's stupid parser while being folded into surrounding whitespace by a html engine.

Of course, it breaks if the output is anything but html... and is just stupid....

Which leads me to the best solution: never use ddoc again.

On Thu, Feb 23, 2017 at 09:35:41PM +0000, Adam D. Ruppe via Digitalmars-d-learn wrote:
> On Thursday, 23 February 2017 at 21:17:33 UTC, H. S. Teoh wrote:
> > 	_Note: Blah blabbety blah
> 
> Nope.
> 
> Ddoc considers [A-Za-z_]+: to be a section header. You can trick it by doing something like
> 
> /++
>  Note: ass
> +/
[...]

Nah, that's overkill. This works:

	Note$(COLON) blah blah blah

Apparently COLON is defined to be ':' in the default ddoc macros, so you needn't define it yourself.


T

-- 
2+2=4. 2*2=4. 2^2=4. Therefore, +, *, and ^ are the same operation.

On Thu, Feb 23, 2017 at 01:39:11PM -0800, H. S. Teoh via Digitalmars-d-learn wrote: [...]
> Nah, that's overkill. This works:
> 
> 	Note$(COLON) blah blah blah
> 
> Apparently COLON is defined to be ':' in the default ddoc macros, so you needn't define it yourself.
[...]

Bah, I was wrong, you *do* need to manually define COLON yourself. :-(

I'm becoming more and more convinced that software that tries to be smart ends up being even dumber than before.  Ddoc trying to automagically turn text into HTML is an example. :-(


T

-- 
Never ascribe to malice that which is adequately explained by incompetence. -- Napoleon Bonaparte

On Thursday, 23 February 2017 at 21:39:11 UTC, H. S. Teoh
> Apparently COLON is defined to be ':' in the default ddoc macros, so you needn't define it yourself.

Oh yeah.

Still, barf.

On 02/23/2017 04:51 PM, Adam D. Ruppe wrote:
> On Thursday, 23 February 2017 at 21:39:11 UTC, H. S. Teoh
>> Apparently COLON is defined to be ':' in the default ddoc macros, so
>> you needn't define it yourself.
>
> Oh yeah.
>
> Still, barf.

Luckily in my case, the "Word:" part is already generated inside a ddoc macro, so it'll be just as well hidden.

What I'd kinda like to do is put together a D doc generator that uses, uhh, probably markdown. But still with some sort of basic (but better-looking than ddoc) macro system, because link URLs can still REALLY clutter up even markdown source and make it unreadable (which is why I actually ended up converting the changelog for at least one of my projects from markdown to ddox.) Not a high enough priority for me now though :(

On 02/23/2017 04:49 PM, H. S. Teoh via Digitalmars-d-learn wrote:
>
> I'm becoming more and more convinced that software that tries to be
> smart ends up being even dumber than before.

I've been convinced of that for a long time ;) Not just software either. Anything. My car does idiotic "smart" junk that irritates the crap out of me and makes me wish my 1997 Prizm hadn't finally rusted itself to pieces. K.I.S.S.

On 02/23/2017 04:34 PM, Ali Çehreli wrote:
>
> (None of the following is tested.)
>
> a) Try using the following macro:
>
>      COLON = :
>
> And then use "Note$(COLON) Blah".
>

Thanks, that works.

> c) Another option:
>
>      NOTE = Note: $0
>
> Then use "$(NOTE Blah)"

Actually, that's more or less what I was already doing anyway (for a changelog):

ENHANCE  = $(LI $(B Enhancement:) $0)
CHANGE   = $(LI $(B Change:) $0)
FIXED    = $(LI $(B Fixed:) $0)

But the section interpretation there wasn't playing nice with newer versions of ddox. Using that "COLON = :" trick fixed it though (and does indeed appear to work outside of these macros, too.