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
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
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
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
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
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
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
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
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
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
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?
DDoc has the following syntax as in "$ should be replaced with &#36;" at http://dlang.org/spec/ddoc.html (None of the following is tested.) a) Try using the following macro: COLON = &#58; And then use "Note$(COLON) Blah". b) Perhaps easier: COLON = &#58; NOTE = Note$(COLON) Then use "$(NOTE) Blah" c) Another option: NOTE = Note&#58; $0 Then use "$(NOTE Blah)" Ali
Feb 23
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:

      COLON = &#58;

 And then use "Note$(COLON) Blah".
Thanks, that works.
 c) Another option:

      NOTE = Note&#58; $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 = &#58;" trick fixed it though (and does indeed appear to work outside of these macros, too.
Feb 23
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