www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Phobos Docs Questions

reply "Confused" <confused about.ddoc> writes:
Recently I've seen documentation work, but am confused about some 
specifics.

I've seen work and/or talk being done towards...

1. Improving the text of the documentation itself
2. Improving ddoc with some Markdown capabilities
3. Moving Phobos docs to page-per-symbol
4. Adding adding discussion to documentation pages
5. Moving Phobos docs from ddoc to ddox

While I appreciate (1) and (2), I don't see the appeal of (3), 
and am strongly opposed to (4) and (5).

As I see it (3) only serves to make it harder to browse the 
documentation and increases server load, but I can probably live 
with it if other people think it is a good idea. I should point 
out that I'm not aware of any other quality web-based docs for 
*anything* that put each symbol on its own page.

I also don't like the idea of (4), because it is a huge extra 
moderation requirement which I don't think this community can 
actually handle, and it will only age, causing it to be yet 
another source of wrong information about Phobos/D.

However, my main concern is with (5), which leads me to some 
questions:

  * If ddoc is good enough for Phobos, why use another 
semi-compatible tool?
  * If ddoc isn't good enough for Phobos, why is it in the 
compiler?
  * If we want ddoc in the compiler, then why not dogfood that for 
Phobos?
  * If we don't want ddoc in the compiler, why is spend time 
improving it?

Thanks.
Jan 11 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/11/15 1:41 PM, Confused wrote:
 Recently I've seen documentation work, but am confused about some
 specifics.

 I've seen work and/or talk being done towards...

 1. Improving the text of the documentation itself
Yes please.
 2. Improving ddoc with some Markdown capabilities
We have https://github.com/D-Programming-Language/dmd/pull/4228 about to make it - for now I think that's going to improve things significantly.
 3. Moving Phobos docs to page-per-symbol
Yah, though quality is not there yet.
 4. Adding adding discussion to documentation pages
Yah.
 5. Moving Phobos docs from ddoc to ddox
Yah, though again we need serious work on quality.
 While I appreciate (1) and (2), I don't see the appeal of (3), and am
 strongly opposed to (4) and (5).

 As I see it (3) only serves to make it harder to browse the
 documentation and increases server load, but I can probably live with it
 if other people think it is a good idea. I should point out that I'm not
 aware of any other quality web-based docs for *anything* that put each
 symbol on its own page.
No worries, the extant docs are here to stay. I plan to put at the beginning of each module a link with text like "See single-page documentation".
 I also don't like the idea of (4), because it is a huge extra moderation
 requirement which I don't think this community can actually handle, and
 it will only age, causing it to be yet another source of wrong
 information about Phobos/D.
The way I see it is: to swim, we gotta get out feet wet.
 However, my main concern is with (5), which leads me to some questions:

   * If ddoc is good enough for Phobos, why use another semi-compatible
 tool?
Mostly because it's there. It's possible to make ddoc generate file-per-entity or automatic cross-indexing. It's been on my list for years, but still haven't gotten to it. So why not just ddox? (It does build now.)
   * If ddoc isn't good enough for Phobos, why is it in the compiler?
ddoc is a terrific and incredibly underrated tool, which can (and should and probably will) be taken further with simple improvements. Note that ddox also works on top of ddoc. Also, again, the ddoc-generated documentation is plenty good and will continue to be available.
   * If we want ddoc in the compiler, then why not dogfood that for Phobos?
It is and it will continue to be there. Oh, one more thing - the website pages proper (language reference) use ddoc.
   * If we don't want ddoc in the compiler, why is spend time improving it?
We do want and we should spend. Andrei
Jan 11 2015