www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDOC adds emphasis on symbols, so how to use $(LINK a) properly?

reply kraybit <hello kraybit.com> writes:
Hello!


Just trying out the built-in ddoc, and it's great!

But is there any way to link to other packages/modules, without 
adding "_" everywhere? Consider:


     // mylib/package.d

     /**
     *  Also see $(LINK mylib.image.pixel.html)
     */
     module mylib;
     ...


This will generate a link, but the href will be 
"<b>mylib</b>.image.pixel.html", which won't work in my browser 
at least (Chromium). This can be fixed with:


     $(LINK _mylib.image.pixel.html)


Ok, great. But wait a minute. How do I know that 'image' and 
'pixel' won't be emphasized symbols in the future? It seems, to 
be sure, I must write:


     $(LINK2 _mylib._image._pixel.html)


And then follows, if I link to any page, I must follow the same 
pattern?


     $(LINK _blog._site._com/_id/3532.html)


I'm not even sure that works. But you see my worry?
How do I use $(LINK)s properly?



Cheers!
Kind regards
/kbit
Dec 01 2015
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 1 December 2015 at 15:15:50 UTC, kraybit wrote:

 But is there any way to link to other packages/modules, without 
 adding "_" everywhere? Consider:


sort of. You could define a custom macro

DDOC_PSYMBOL=$0

I think anyway... to make it just emit the original text without 
the <b> tag.



I think the automatic emphasis is a mistake anyway because it 
often highlights homonyms which is just silly looking. Do perhaps 
disabling it with the above macro is a good idea, then you can 
manually $(B it) when you want it to be bolded instead of _ing it 
when you don't want it bolded.
Dec 01 2015
parent kraybit <hello kraybit.com> writes:
On Tuesday, 1 December 2015 at 15:32:56 UTC, Adam D. Ruppe wrote:

 On Tuesday, 1 December 2015 at 15:15:50 UTC, kraybit wrote:

 But is there any way to link to other packages/modules, 
 without adding "_" everywhere? Consider:


 sort of. You could define a custom macro

 DDOC_PSYMBOL=$0

 I think anyway... to make it just emit the original text 
 without the <b> tag.



 I think the automatic emphasis is a mistake anyway because it 
 often highlights homonyms which is just silly looking. Do 
 perhaps disabling it with the above macro is a good idea, then 
 you can manually $(B it) when you want it to be bolded instead 
 of _ing it when you don't want it bolded.



Thanks, that worked!
I'm happy :)


Cheers!
Dec 01 2015
prev sibling next sibling parent reply anonymous <anonymous example.com> writes:
On 01.12.2015 16:15, kraybit wrote:

      /**
      *  Also see $(LINK mylib.image.pixel.html)
      */
      module mylib;
      ...


 This will generate a link, but the href will be
 "<b>mylib</b>.image.pixel.html", which won't work in my browser at least
 (Chromium). This can be fixed with:


      $(LINK _mylib.image.pixel.html)


 Ok, great. But wait a minute. How do I know that 'image' and 'pixel'
 won't be emphasized symbols in the future?


'mylib' is emphasized because it's the module name and you're 
documenting the module declaration there. That is, identifiers are only 
emphasized automatically when they're used in the declaration that is 
being documented. 'image' or 'pixel' would only be emphasized if you 
changed the module name to 'image' or 'pixel'.
Dec 01 2015
parent reply kraybit <hello kraybit.com> writes:
On Tuesday, 1 December 2015 at 15:33:59 UTC, anonymous wrote:

 On 01.12.2015 16:15, kraybit wrote:

      /**
      *  Also see $(LINK mylib.image.pixel.html)
      */
      module mylib;
      ...


 This will generate a link, but the href will be
 "<b>mylib</b>.image.pixel.html", which won't work in my 
 browser at least
 (Chromium). This can be fixed with:


      $(LINK _mylib.image.pixel.html)


 Ok, great. But wait a minute. How do I know that 'image' and 
 'pixel'
 won't be emphasized symbols in the future?


 'mylib' is emphasized because it's the module name and you're 
 documenting the module declaration there. That is, identifiers 
 are only emphasized automatically when they're used in the 
 declaration that is being documented. 'image' or 'pixel' would 
 only be emphasized if you changed the module name to 'image' or 
 'pixel'.


Hm, I see, so it's contextual? Would 'pixel' then be emphasized 
if I'm in the documentation of void pixel()?

I just get the feeling I need to think before using LINK. I'd 
like to not think, too  much. It doesn't also seem clear when 
this happens. Will $(LINK forum.com/pixel/98) work? Or does it 
need a "_"?

Anyway, turning it off is good enough for me.

Thanks for the reply!
Dec 01 2015
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 1 December 2015 at 15:52:04 UTC, kraybit wrote:

 Hm, I see, so it's contextual? Would 'pixel' then be emphasized 
 if I'm in the documentation of void pixel()?


Yes. It underlines whatever the currently documented symbol is. 
So at the top level, it is the module/package name. On a class, 
it is the class name. Method, you get the point.

That's the extent of the context though... if you write:

/// Call are when you are sure you are ready.
void are() {}


Every instance of the word "are" in the documentation would get 
the PSYMBOL treatment, whether it is grammatically correct, in a 
link, in a table, or whatever.

But it would not be highlighted if the method was different:

/// Call foo when you are ready.
void foo() {}


There, foo would be highlighted, but are wouldn't be.
Dec 01 2015
prev sibling parent anonymous <anonymous example.com> writes:
On 01.12.2015 16:52, kraybit wrote:

 Hm, I see, so it's contextual? Would 'pixel' then be emphasized if I'm
 in the documentation of void pixel()?


Yes and yes.


 I just get the feeling I need to think before using LINK. I'd like to
 not think, too  much.


It's a clever feature for sure. Maybe too clever, or not clever enough.


 It doesn't also seem clear when this happens. Will
 $(LINK forum.com/pixel/98) work? Or does it need a "_"?


I don't have memorized what's a word boundary for Ddoc, and the 
documentation is sparse. You'd have to try it out, I guess.
Dec 01 2015
prev sibling parent kraybit <hello kraybit.com> writes:
Just wanna follow up.


Thanks for the replies everyone. Helped a lot!


***


Hmm, this might be out of line, but I can't help myself. I got an 
idea. I guess a nice feature would be something like a built-in 
clean representation of macro arguments, so that you could define 
LINK as


     LINK = <a href="$_0">$0</a>


Or perhaps an immutable built-in macro?


     LINK = <a href="$(CLEAN $0)">$0</a>


And then it would always work? I mean it seems most macros 
generate HTML, and then anything is fine really. But there are 
those special cases when you're generating something other than 
HTML, such as an URL, or even JavaScript-code, and you really 
need to get rid of all "cleverness".

I've understood you always end posts like this with:
Destroy!

So there, I did it :)
Cheers!
Dec 02 2015