www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - current ddoc state of the art

reply "Adam D. Ruppe" <destructionator gmail.com> writes:
Let's try to get state-of-the-art ddoc in here. Iff my backtick 
PR goes through, I'll do another one bringing some of these 
tricks to the default macro list.

What I want to do in this thread is get the nicest ddoc bits we 
can do and analyze where they fail. If they rock, let's just put 
those macros in the default set and document how to do it.

If they still suck, then maybe we can discuss using an 
alternative.



First, lists. The current default macro is ok:

$(UL
    $(LI item)
    $(LI item)
)


But ddoc supports tail recursion which means we could:

         Macros:
                 LIST=$(UL $(XLIST $1)$(XLIST $+))
                 XLIST=$(LI $1)$(XLIST $+)
                 L=$0

Then do:

$(LIST
         foo,
         bar,
         $(L item, with, comma),

)


That's perhaps better. The $(L macro is still needed for some 
literal text passing - you can do a comma, a dollar sign, or 
matching parens in there.

I think of it like being the quotes in a CSV file. Not needed if 
there's no commas, available if there is.


The leading whitespace is kept on each item btw, but ignored by 
html output, so it is OK on the web.



I honestly think that's good enough.


We can do similar with tables:



$(TABLE
	$(TROW Some header, 	Some other header, 	Third header)
	$(TROW Some row, 	Some other row, 	More info)
)


The problem is if the data is so long you'd like to break it onto 
another line, but then the look is ruined.



$(TABLE
	$(TROW Some header, 	Some other header, 	Third header)
	$(TROW Some row that
                is really long, 	Some other row, 	More info that
                                                         is really 
long)
)


That works, it generates usable output, the long items don't 
match up anymore in the source. It might be hard to read.


One idea is to use macros as a kind of footnote to reference long 
data elsewhere:

$(TABLE
	$(TROW Some header, 	Some other header, 	Third header)
	$(TROW Some row, 	$(Long_data_here), 	$(fooa))
)

Macros:
     fooa=cool
     Long_data_here=We can put some longer data here
         and it should work a lot nicer.



There's a few problems with that:

   * the data doesn't appear where you want; you'd have to scroll 
back and forth to actually read the table.

   * Two functions that define the same macro name will override 
each other; a doc from way down the file could wipe out your 
footnote from up top.



So I think the state of the art ddoc table leaves something to be 
desired. A markdown table syntax might be cool here.

Another thing that might help is scoping the macro definitions to 
the symbol's scope. A macros: section on a module definition 
defines macros usable throughout the whole file. On a class, 
itself and its members. On an individual member, it only applies 
there.

That could allow and encourage the use of local macros for all 
kinds of little things including footnotes.




Remember, the purpose of this thread is to try to get as good as 
we can for various tasks with the existing ddoc capabilities. 
Only if that comes up short do we want to talk improvements, and 
even then, I want this thread to be conservative.
Jan 01 2015
next sibling parent reply "Dicebot" <public dicebot.lv> writes:
As long as you are actually forced to use _any_ kind of macros in 
basic documentation it won't be good enough.

Raw source is most commonly read form of any documentation 
(unless it is Phobos or other stdlib) and it is most important 
one. Looking acceptable is not enough, raw documentation code 
must look _pretty_, which means being decently decorated in that 
raw form already.

Macros are not pretty. Even clever cute macros are not pretty.
Jan 01 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 10:04 AM, Dicebot wrote:

 As long as you are actually forced to use _any_ kind of macros in basic
 documentation it won't be good enough.



Basic documentation can be written without any macros:


/****************************
This function does blah, blah, blah.

Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly.

Params:
    x = the awesome input value

Returns:
    insightful description of the return value

Example:
---
int foo(int x) { ... stunning D code ... }
---
***************************/

Can you do lists without macros in Ddoc? Sure:

/**************************************

  Description

  1. first item

  2. second item

An unordered list:

  - first item

  - second item

**********************************/
Jan 01 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Jan 01, 2015 at 12:48:58PM -0800, Walter Bright via Digitalmars-d wrote:
[...]

 Can you do lists without macros in Ddoc? Sure:
 
 /**************************************
 
  Description
 
  1. first item
 
  2. second item
 
 An unordered list:
 
  - first item
 
  - second item
 
 **********************************/


The problem is that this is strictly speaking a hack, not a solution,
because in the output it's not tagged as a list. This may not be a
problem if the output is HTML for user consumption, but if you're
outputting to XML, say, or if your HTML is postprocessed by semantic
analysis tools, they will fail to pick up on the fact that this is a
list.


T

-- 
Unix was not designed to stop people from doing stupid things, because that
would also stop them from doing clever things. -- Doug Gwyn
Jan 01 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 1:49 PM, H. S. Teoh via Digitalmars-d wrote:

 The problem is that this is strictly speaking a hack, not a solution,
 because in the output it's not tagged as a list. This may not be a
 problem if the output is HTML for user consumption, but if you're
 outputting to XML, say, or if your HTML is postprocessed by semantic
 analysis tools, they will fail to pick up on the fact that this is a
 list.


I know it's not tagged as a list, but it does show up in the browser as a 
reasonable list.

The thing is, basic documentation can be done in Ddoc without using any macros
- 
lists are not used in the vast majority of function descriptions. Using:

   $(LIST
      item1,
      item2,
      item3
    )

for the occasional use is simply not that heinous. Lists can also be styled in 
quite a variety of ways; with a special syntax for them they can only be styled 
one way across the entire document. It turns out that Ddoc usage has leaned 
towards using a lot of custom styling, because it's easy to do.
Jan 01 2015
next sibling parent reply Mike Parker <aldacron gmail.com> writes:
On 1/2/2015 7:10 AM, Walter Bright wrote:

 On 1/1/2015 1:49 PM, H. S. Teoh via Digitalmars-d wrote:

 The problem is that this is strictly speaking a hack, not a solution,
 because in the output it's not tagged as a list. This may not be a
 problem if the output is HTML for user consumption, but if you're
 outputting to XML, say, or if your HTML is postprocessed by semantic
 analysis tools, they will fail to pick up on the fact that this is a
 list.


 I know it's not tagged as a list, but it does show up in the browser as
 a reasonable list.

 The thing is, basic documentation can be done in Ddoc without using any
 macros - lists are not used in the vast majority of function
 descriptions. Using:

    $(LIST
       item1,
       item2,
       item3
     )

 for the occasional use is simply not that heinous. Lists can also be
 styled in quite a variety of ways; with a special syntax for them they
 can only be styled one way across the entire document. It turns out that
 Ddoc usage has leaned towards using a lot of custom styling, because
 it's easy to do.


So then Ddoc features become like C++ features -- usage varies across 
projects. Those who hate the visual noise won't use the macros, others 
will use macros all over the place, but they won't necessarily be the 
same from project to project with people defining custom macros.

Personally, I like the simple, macroless form of Ddoc just fine. It's 
what I use for my stuff. But looking at the Phobos docs gives me a 
headache. Contributing to the documentation requires learning the 
difference between all the different macros (XREF,LINK2,FULL_XREF...). 
Not impossible, but it can turn what you think is going to be a simple 5 
minute change into a rather longer process.

The macro system provides a great deal of flexibility, but it sucks in 
terms of readability no matter how it's formatted. The Ddoc generator 
can process it wonderfully -- my brain, not so much. It also doesn't 
encourage any sort of consistency at all. The thing about JavaDoc or 
DOxygen is that no matter which project source I'm looking at, the 
comment tags not only don't get in the way, but if I want to contribute 
I know exactly which tags to use.

Besides, consider how many tasks the macros in Phobos handle that are 
common enough for most projects to need them. Shouldn't that sort of 
thing be built in? Why should we keep putting together LIST macros when 
a list is a very common documentation feature? It's nice to be able to 
redefine that macro for different types of markup output, but I would 
much rather see a standard list tag that simply outputs HTML. I can use 
one of several tools to convert the HTML to something else if I need to.
Jan 01 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 5:47 PM, Mike Parker wrote:

 On 1/2/2015 7:10 AM, Walter Bright wrote:
 Besides, consider how many tasks the macros in Phobos handle that are common
 enough for most projects to need them. Shouldn't that sort of thing be built
in?
 Why should we keep putting together LIST macros when a list is a very common
 documentation feature? It's nice to be able to redefine that macro for
different
 types of markup output, but I would much rather see a standard list tag that
 simply outputs HTML. I can use one of several tools to convert the HTML to
 something else if I need to.


Because all those features come up with the cost, such as adding a way to work 
around them.

BTW, you can embed HTML directly. No need to use the macros.
Jan 01 2015
prev sibling parent "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
On Thursday, 1 January 2015 at 22:11:08 UTC, Walter Bright wrote:

 entire document. It turns out that Ddoc usage has leaned 
 towards using a lot of custom styling, because it's easy to do.


I always wondered why the documentation of each Phobos module 
looks different.
Jan 02 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 9:35 AM, Adam D. Ruppe wrote:

 [snip]

 Remember, the purpose of this thread is to try to get as good as we can
 for various tasks with the existing ddoc capabilities. Only if that
 comes up short do we want to talk improvements, and even then, I want
 this thread to be conservative.


Genius. Thanks for the awesome insights. We should redo lists and tables 
per your outline. -- Andrei
Jan 02 2015