www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - ddoc: Can I escape a colon?

reply "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
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?
Feb 23 2017
next sibling parent reply "H. S. Teoh via Digitalmars-d-learn" <digitalmars-d-learn puremagic.com> writes:
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.
Feb 23 2017
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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

/++
&#x20;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.
Feb 23 2017
next sibling parent reply "H. S. Teoh via Digitalmars-d-learn" <digitalmars-d-learn puremagic.com> writes:
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
 
 /++
 &#x20;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.
Feb 23 2017
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Feb 23 2017
parent reply "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
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 :(
Feb 23 2017
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 24 February 2017 at 02:50:27 UTC, Nick Sabalausky 
(Abscissa) wrote:

 What I'd kinda like to do is put together a D doc generator 
 that uses, uhh, probably markdown.


My dpldocs.info generator continues to progress and I'm almost 
ready to call it beta and let other people use it.

It's syntax is a hybrid of ddoc and markdown. Take a look at the 
sample page: http://dpldocs.info/experimental-docs/test.html

Though I don't support user-defined macros, it just has a 
hardcoded list of common ones to support Phobos source, and then 
a bunch of "magic macros" and a few special syntaxes for really 
common things.

Like for links, I went with a Wikipedia-inspired [url|text] 
bracket. (or if it is just a url, you don't need to bracket it at 
all). You can also mention a name there, and it searches your 
imported namespaces to look it up.

import std.range;
/// See [isOutputRange] for more.
void foo() {}


That [isOutputRange] will look it up inside std.range and link 
straight to std.range.primitives.isOutputRange.

Or you can do like [http://dlang.org|The official D Website] and 
it will turn that into the natural <a href="http://dlang.org>The 
official D Website</a> for you.

There's a few more syntax things you can see in that sample link 
above and a few more I have planned, but I find it is already 
really pretty usable. And then, of course, it has enough 
knowledge of D to make even complex functions look pretty 
readable:

http://dpldocs.info/experimental-docs/std.algorithm.sorting.sort.html

http://dpldocs.info/experimental-docs/arsd.simpledisplay.SimpleWindow.this.1.html

and so on.
Feb 23 2017
parent "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
On 02/23/2017 10:36 PM, Adam D. Ruppe wrote:

 On Friday, 24 February 2017 at 02:50:27 UTC, Nick Sabalausky (Abscissa)
 wrote:

 What I'd kinda like to do is put together a D doc generator that uses,
 uhh, probably markdown.


 My dpldocs.info generator continues to progress and I'm almost ready to
 call it beta and let other people use it.

 It's syntax is a hybrid of ddoc and markdown. Take a look at the sample
 page: http://dpldocs.info/experimental-docs/test.html


Oh, nice. The $(MATH stuff is especially cool (although unlikely to be 
useful in my libs - damn! I wanna put that to use!).

Looking forward to seeing that hit beta (and beyond) and trying that out.
Feb 23 2017
prev sibling parent reply "H. S. Teoh via Digitalmars-d-learn" <digitalmars-d-learn puremagic.com> writes:
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
Feb 23 2017
parent "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
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.
Feb 23 2017
prev sibling next sibling parent reply =?UTF-8?Q?Ali_=c3=87ehreli?= <acehreli yahoo.com> writes:
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?




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

(None of the following is tested.)

a) Try using the following macro:



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

b) Perhaps easier:


     NOTE = Note$(COLON)

Then use "$(NOTE) Blah"

c) Another option:



Then use "$(NOTE Blah)"

Ali
Feb 23 2017
parent "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
On 02/23/2017 04:34 PM, Ali Çehreli wrote:

 (None of the following is tested.)

 a) Try using the following macro:



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


Thanks, that works.


 c) Another option:



 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 

does indeed appear to work outside of these macros, too.
Feb 23 2017
prev sibling parent Alexandru Ermicioi <alexandru.ermicioi gmail.com> writes:
On Thursday, 23 February 2017 at 21:04:39 UTC, 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?


You can put a space before : and ddoc, or ddox won't treat it as 
a section.
-----------------
Note : Blah blabbety blah
-----------------
Feb 26 2017