On 12/31/13 9:39 AM, Sönke Ludwig wrote:
> Am 31.12.2013 17:48, schrieb Andrei Alexandrescu:
>> In a nutshell, "good cross-referencing is hard".
>
> I don't think so at all (on the technical level). What is the issue with
> using the #identifier.chain pattern for example? It seems simple enough
> and I can't imagine a more natural thing than to reference symbols in
> documentation the same way as in code.

I see #identifier.chain similar to e.g. $(X identifier.chain) so no issue with that. It just adds more syntax without necessity. I'd instead work on improving macros to generate proper xrefs out of $(X ...) rather than adding new syntax. But either way is fine.

>> That's exactly the
>> experience of anyone who's created an index. In publishing there are
>> automatic index generators and they're universally known to be vastly
>> inferior to professional-produced ones. I've created my own index by
>> hand for TDPL and it's been difficult, but probably the result is better
>> than an automated index.
>>
>
> But index generation is a higher level issue. The basis for it is to
> have some kind of universal anchor that can be used as a reference.
> #identifier.chain or $(REF identifier.chain) is nothing more than that
> and just solves the issue of supporting arbitrary nested scopes and
> different file system or document hierarchies.

Agreed. In all likelihood I misunderstood something because I thought you were referring to cross-referencing text without any user intervention.


Andrei

On Tue, Dec 31, 2013 at 09:08:07AM -0800, Andrei Alexandrescu wrote:
> On 12/31/13 4:26 AM, Jacob Carlborg wrote:
[...]
> >>>4. It doesn't rely on embedded HTML, as such will impede extraction and formatting for other purposes.
> >
> >As far as I know this isn't very useful. For the other formats we use, like PDF, it uses the HTML output as a base.
> 
> Again no. You are misinformed. The PDF manual is generated via LaTeX from the same ddoc sources as the HTML pages.
[...]

This is true.

I will note, however, that limitations in Ddoc make the LaTeX output less than ideal. Many fine points of LaTeX formatting are ignored or simply not possible (e.g., proper use of em- and en-dashes, proper use of '.\ ', non-breaking spaces, hyphenation hints, etc.). In some cases, postprocessing is needed to take full advantage of the LaTeX format (esp. for display of math formulas, which is one of LaTeX's biggest selling points).

Even for HTML, the lack of semantic support for paragraphs means XHTML compliance is out of the question, and any proper tag nesting where paragraphs are involved is a fragile hack that is likely non-HTML compliant. But nobody notices this because most browsers are too permissive in what they accept.

So even though I think Ddoc isn't as bad as some people make it out to be, I'm still on the fence about it.


T

-- 
By understanding a machine-oriented language, the programmer will tend to use a much more efficient method; it is much closer to reality. -- D. Knuth

On 12/31/2013 4:37 AM, Jacob Carlborg wrote:
> That doesn't sound very efficient.

You don't need an efficient solution for ddoc files of readable size. It only takes a few moments. I've spent far, far more time typing about it here than it took to do. Some solutions are simply not worth the bother.

> Regardless of that, the current macros still
> don't work. How do you do cross referencing for something that has a deeper
> hierarchy and what most of Phobos has?
>
> Just take a look at the documentation of std.digest.crc[1]. None of the cross
> referencing to std.digest.digest.toHexString work. It's due to a
> misconception of how the $(XREF) works.

Using the macros incorrectly is not necessarily an indictment of macros.

On 12/31/2013 4:14 AM, Jacob Carlborg wrote:
> If Ddoc requires post processing to be useful it's a complete failure.

Not at all. The same ddoc sources are used to generate an ebook and a Windows help file - which are based on html but require different html to be generated, a difference handled by ddoc. The ebook and chm both require post processing with tools supplied by Amazon and Microsoft, respectively.

It works, it is not a failure because the source files do not need to be modified to get this working. A failure would be having to modify the source files each time a different output needs to be generated.


> Why don't we instead strive to make it the best documentation generator for D?

We all of course want that - but there is certainly room for disagreement about what "best" is.

Reinventing Amazon's "kindlegen.exe" seems pointless to me.

On 2013-12-31 19:16, Andrei Alexandrescu wrote:

> Agreed. In all likelihood I misunderstood something because I thought
> you were referring to cross-referencing text without any user intervention.

I made two suggestions, one which is completely automatic and one which requires some syntax. It seems most posts here only address the first suggestion.

-- 
/Jacob Carlborg

On 2013-12-31 21:52, Walter Bright wrote:

> You don't need an efficient solution for ddoc files of readable size. It
> only takes a few moments. I've spent far, far more time typing about it
> here than it took to do. Some solutions are simply not worth the bother.

I've probably spent at least as much time on the documentation as on the code for std.serialization/Orange. The documentation could still be improved a lot, like more cross referencing. That's why I started this thread.

> Using the macros incorrectly is not necessarily an indictment of macros.

So which macro should I use to make cross referencing for arbitrary deep hierarchies?

-- 
/Jacob Carlborg

On 12/31/2013 1:17 PM, Jacob Carlborg wrote:
> So which macro should I use to make cross referencing for arbitrary deep
> hierarchies?

I used this one in std.datetime:

        LREF2=<a href="#$1">$(D $2)</a>

On Tuesday, 31 December 2013 at 10:37:23 UTC, Sönke Ludwig wrote:
> Am 31.12.2013 11:05, schrieb Vladimir Panteleev:
>> P.S. How come your user agent (Thunderbird) is not emitting
>> format=flowed messages? According to [1], it supports format=flowed, and
>> can only be disabled via editing option strings.
>>
>> [1]:
>> http://kb.mozillazine.org/Plain_text_e-mail_(Thunderbird)#Flowed_format
>
> Although I can't promise that I didn't tamper with these settings, I didn't find any non-default value in about:config in that area, but there is a default setting "mailnews.send_plaintext_flowed = false". This is now manually set to true, let's see.

Did you install the Enigmail extension? It seems to have a bug which turns off format=flowed generation even if you never use it.

On 12/31/13 11:51 AM, H. S. Teoh wrote:
> On Tue, Dec 31, 2013 at 09:08:07AM -0800, Andrei Alexandrescu wrote:
>> On 12/31/13 4:26 AM, Jacob Carlborg wrote:
> [...]
>>>>> 4. It doesn't rely on embedded HTML, as such will impede extraction
>>>>> and formatting for other purposes.
>>>
>>> As far as I know this isn't very useful. For the other formats we
>>> use, like PDF, it uses the HTML output as a base.
>>
>> Again no. You are misinformed. The PDF manual is generated via LaTeX
>> from the same ddoc sources as the HTML pages.
> [...]
>
> This is true.
>
> I will note, however, that limitations in Ddoc make the LaTeX output
> less than ideal. Many fine points of LaTeX formatting are ignored or
> simply not possible (e.g., proper use of em- and en-dashes, proper use
> of '.\ ', non-breaking spaces, hyphenation hints, etc.). In some cases,
> postprocessing is needed to take full advantage of the LaTeX format
> (esp. for display of math formulas, which is one of LaTeX's biggest
> selling points).
>
> Even for HTML, the lack of semantic support for paragraphs means XHTML
> compliance is out of the question, and any proper tag nesting where
> paragraphs are involved is a fragile hack that is likely non-HTML
> compliant. But nobody notices this because most browsers are too
> permissive in what they accept.

These should be fixed in ddoc.

Andrei

Am 01.01.2014 02:21, schrieb Vladimir Panteleev:
> On Tuesday, 31 December 2013 at 10:37:23 UTC, Sönke Ludwig wrote:
>> Am 31.12.2013 11:05, schrieb Vladimir Panteleev:
>>> P.S. How come your user agent (Thunderbird) is not emitting
>>> format=flowed messages? According to [1], it supports format=flowed, and
>>> can only be disabled via editing option strings.
>>>
>>> [1]:
>>> http://kb.mozillazine.org/Plain_text_e-mail_(Thunderbird)#Flowed_format
>>
>> Although I can't promise that I didn't tamper with these settings, I
>> didn't find any non-default value in about:config in that area, but
>> there is a default setting "mailnews.send_plaintext_flowed = false".
>> This is now manually set to true, let's see.
>
> Did you install the Enigmail extension? It seems to have a bug which
> turns off format=flowed generation even if you never use it.

Yep, that seems to be it. Good to know, I've never noticed that up to now.