On Monday, 29 December 2014 at 23:53:01 UTC, Walter Bright wrote:
> (And I should ask, what if you wanted a | in the Markdown?)

I have no idea; I don't use it either, I just write plain text nowadays. It is easy to write and plenty legible in source code or extracted formats.

On 12/29/2014 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
> We've already had to resort to $(COMMA) hacks to work around comma
> issues in Phobos docs. :-(

It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup.


> Not to mention that as it stands, ddoc is only really convenient for
> HTML output; while it's certainly *possible* to target it for non-HTML
> output, it's a pain.

More correctly, Ddoc works well for any markup that has a fundamentally nested structure. LaTeX does not. But at least you can make it work with LaTeX. Whatcha gonna do with Markdown?

Ddoc has worked extremely well for being adaptible for different HTML output - like the online docs have undergone numerous facelifts while requiring zero changes to the Ddoc source code. It also has been able to generate ebooks from the documentation, again with zero source code changes, just a new set of macro definitions.

CandyDoc has been done with it, also with zero source changes.

On 12/29/2014 3:59 PM, Adam D. Ruppe wrote:
> On Monday, 29 December 2014 at 23:53:01 UTC, Walter Bright wrote:
>> (And I should ask, what if you wanted a | in the Markdown?)
>
> I have no idea; I don't use it either, I just write plain text nowadays. It is
> easy to write and plenty legible in source code or extracted formats.

And that works, too!

What I do is type out a stream of consciousness, and get all the text right. I only add markup as a last pass.

On Monday, 29 December 2014 at 23:56:47 UTC, Walter Bright wrote:
> On 12/29/2014 3:31 PM, Kiith-Sa wrote:
>> because I need macros even for something as common as an inline code fragment.
>
> Markup, macro, same thing.
>
>
>> Not to mention, if I include the full table lines, not just ~70 chars this
>> newsgroup will take, the difference in readability is much more massive.
>
> Not really, because you can create your own custom macros to shorten things up.
>
> I use Ddoc all the time, and I create custom macros ALL THE TIME for semantic shortcuts, prettying things up, saving typing, etc. Any repetitive tasks are candidates for a custom macro.
>
> If you're not using custom macros, and you find Ddoc tedious and repetitive, you're using it wrong.

I cannot use a custom macro to shorten $(D a == b). A well-written paragraph will have 20 such $(D XXX), $(B XXX), $(I XXX), not to mention $(SOMELINK xxx.com XXX). And there's no way to make lists or tables readable: *unless* their contents is homogenous, at best I will have rows full of $(XXX ).
etc. is completely unreadable for anyone but people who have spent at least a year looking at the mess that is Phobos documentation comments.
Javadoc is more readable in sources, as is Doxygen. Python's Sphinx is more readable in their sources. [Rust](http://doc.rust-lang.org/rustdoc.html) is using markdown for their documentation and they don't have any issues either.

Yes, *you* use DDoc all the time. But *you* are also forcing it on everyone using the language, and on any average programmer who may potentially use D, most of whom don't share your love for macros and MANY of whom know much more common formats like Markdown. Most people don't write their docs in LaTeX either.

Besides, no-one is proposing to *remove* the macros, the proposal it to add syntax for basic cases which frankly can *not* be made any less ugly with macros. And yeah, so you will need to escape

I'm writing my *thesis* in ReStructuredText, which is basically Markdown on steroids with *way* more special characters than Markdown, and I almost never need to escape anything.


Either way, I'm done with this argument, I expect it will take many more pissed-off users for this to change.



As for the CSS thing, yes, you need that built in. It doesn't have to be amazing but it *has to be usable*.

to be usable, documentation must be as simple to generate as:

  doxygen Doxyfile


That's what a user coming from most different languages expects, if they don't get it, it seems *broken* and is extremely off-putting. When I was starting with D this almost made me give up. Bare HTML files, no cross-referencing, unreadable, no menu. No information on the site on how to get a usable documentation (not sure how it's now, it's been a few years), and coming from Doxygen, writing a bunch of .ddoc files I wasn't even told about wasn't what would come to my mind.

The default does not need to look amazing, but there must be something usable to start with, without *any* work other than having documentation comments in your code. Any other common documentation generator will produce something that can at least be browsed.

On Mon, Dec 29, 2014 at 04:10:35PM -0800, Walter Bright via Digitalmars-d wrote:
> On 12/29/2014 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
> >We've already had to resort to $(COMMA) hacks to work around comma
> >issues in Phobos docs. :-(
> 
> It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup.

I wasn't defending Markdown, btw. As you pointed out elsewhere, it does have its own set of limitations... but OTOH, it was never *designed* to be all-encompassing. It was just an attempt to reduce the tedium of HTML tag soup by using shorter, more visually-appealing syntax to represent some of the most common constructs. I'm not a big fan of Markdown, though. It's better than raw HTML, but only just so.


> >Not to mention that as it stands, ddoc is only really convenient for HTML output; while it's certainly *possible* to target it for non-HTML output, it's a pain.
> 
> More correctly, Ddoc works well for any markup that has a fundamentally nested structure. LaTeX does not.

That's not true; LaTeX supports nested structures quite well.


> But at least you can make it work with LaTeX. Whatcha gonna do with Markdown?

Again, I wasn't defending Markdown.


> Ddoc has worked extremely well for being adaptible for different HTML output

Yes, it works well with HTML, but not so well for other output formats.


> - like the online docs have undergone numerous facelifts while requiring zero changes to the Ddoc source code. It also has been able to generate ebooks from the documentation, again with zero source code changes, just a new set of macro definitions.
> 
> CandyDoc has been done with it, also with zero source changes.

This is not really accurate... if all you care for is plain text copy-n-pasted from source code comments, with a smattering of tags added on top to eliminate the most egregious eyesores, then sure, you can just write straight text in the ddoc comments and it will Just Work(tm).

But as soon as you try to do anything more with it -- output correctly-formed XHTML, for example, ddoc doesn't work.  Try making it output paragraphs correctly encapsulated in <p>...</p> blocks sometime. It doesn't work, because ddoc doesn't understand what paragraphs are, it only knows what blank lines are, but blank lines are not a reliable indicator of paragraph breaks (e.g., what about the break between a section heading and a paragraph? Or between a quoted code block and a paragraph before/after the code?).

The only way to get it right is to turn your ddoc comments into tag soup. Are you seriously suggesting that we have to write ddoc tag soup while coding? Or that we first write in plain text then go back afterwards and wrap every paragraph in $(P ...) macros? The only reason zero source code changes were required, was because the ddoc comments were already written with the requisite tag soup to begin with. Which is OK, if that's the "correct" way to use ddoc... but in that case, the page on dlang.org that describes ddoc should be revised to not give the false impression that you can just write documentation comments in plain text format and expect to get nice output from it.


T

-- 
Живёшь только однажды.

On 12/29/14 8:49 PM, Walter Bright wrote:
> On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
>> Ddoc isn't too bad, but trying to document examples in dom.d turned
>> into a mess
>> of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
>
> I'd make a macro:
>
>     XML=$(LT)$0/$(GT)
>
> I use custom macros all the time in Ddoc. If you aren't, you're not
> doing it right :-)

Macros are for code, not for documentation.

When wanting to contrirbute documentation you'll have to learn which macros the author defined and which ones to use. Again, this makes it harder to write docs, not easier.

On Monday, 29 December 2014 at 23:13:32 UTC, Walter Bright wrote:
> If you know how to do it, submit a PR!

Eh, the other definitions need to be changed to add the correct data which is a bit tedious to ensure it is all covered... and I personally don't care that much, since I don't use it anyway.

On 12/29/2014 4:45 PM, H. S. Teoh via Digitalmars-d wrote:
>>> Not to mention that as it stands, ddoc is only really convenient for
>>> HTML output; while it's certainly *possible* to target it for
>>> non-HTML output, it's a pain.
>>
>> More correctly, Ddoc works well for any markup that has a
>> fundamentally nested structure. LaTeX does not.
>
> That's not true; LaTeX supports nested structures quite well.

'Supports' is not the same thing as 'is' a nested structure.


>> But at least you can make it work with LaTeX. Whatcha gonna do with
>> Markdown?
> Again, I wasn't defending Markdown.

Then I'm a bit lost on what the point of complaining about Ddoc is. Are you arguing that Ddoc should implement LaTeX?



> The only way to get it right is to turn your ddoc comments into tag
> soup. Are you seriously suggesting that we have to write ddoc tag soup
> while coding? Or that we first write in plain text then go back
> afterwards and wrap every paragraph in $(P ...) macros? The only reason
> zero source code changes were required, was because the ddoc comments
> were already written with the requisite tag soup to begin with. Which is
> OK, if that's the "correct" way to use ddoc... but in that case, the
> page on dlang.org that describes ddoc should be revised to not give the
> false impression that you can just write documentation comments in plain
> text format and expect to get nice output from it.

I think this is an unfair critique. The blank lines separating paragraphs work fine.

Ddoc is not intended to be LaTeX. That it can't do everything a professional typesetting language can is not remarkable, no other markup language can, either.

So what's nice about ddoc is it understands the language. I think it should know scoping too.

Let's forget about the syntax for a moment and think of a feature I'd really like: automatic linkability to mentioned symbols.


module ddoc_test;
import module_with_baz;

void bar() {}

/// See also: $(DSYMBOL bar), $(DSYMBOL baz)
void foo() {}


I think it'd be great if it could recognize bar in there as a symbol and actually look it up in the current scope. Then you can define a macro to link it.

So it would translate it to $(DSYMBOL ddoc_test.bar bar) and $(DSYMBOL module_with_baz.baz baz) and the rest of the code is responsible for figuring out how to actually link to it.

The first argument it translates is the fully-qualified name determined by scope lookup rules. The second argument is what the user actually typed in there.


This would use the fact that ddoc is in the compiler to provide something compelling that is hard to do in an external program. Changing syntax is easy - dmd -D -X makes the json file which you can parse and make your own doc displayer. Getting scope names is hard though.

On 12/29/14 12:04 PM, Jacob Carlborg wrote:
> On 2014-12-29 20:48, Walter Bright wrote:
>
>> I don't care much for hybrids, they are confusing and ugly.
>
> Markdown already support raw HTML. We could use Markdown but with Ddoc
> macros instead of raw HTML.
>
> BTW, Ddoc macros are really ugly.

Ideas for a better syntax? I like the idea of a uniform syntax for all macros instead of learning one syntax for each artfact. -- Andrei