[CFR] Migrating the documentation to a real XML toolchain

[Gabor Kovesdan]

Em 15-03-2013 00:33, Warren Block escreveu:
> On Thu, 14 Mar 2013, Gabor Kovesdan wrote:
>
>> Em 27-02-2013 02:24, Warren Block escreveu:
>>> Author info is a little off.  Compare the authors at the start of 
>>> the bsdinstall chapter:
>>> http://people.freebsd.org/~gabor/db45/en_US.ISO8859-1/books/handbook/bsdinstall.html 
>>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/bsdinstall.html 
>>>
>>>
>>> In the standard version, each section is rendered as a sentence, 
>>> with multiple authors separated by commas.
>>>
>>> Acronyms don't have any highlights, they just look like normal text.
>>>
>> Thank you Warren for the exhaustive list, I've been fixing the issues 
>> you reported. However, I don't find highlighted acronyms in the old 
>> rendering either. Could you please point me to a concrete example, 
>> please?
>
> Good question.  I know this is given as a reason why acronyms should 
> always be marked up, and I thought I'd seen it at some point in the 
> FreeBSD docs.  But it does not do it now, and I may have been looking 
> at something else.  It is something that would really benefit the reader. 
I also agree that it would be a nice feature but actually I don't even 
understand how it is supposed to work at the moment. In most cases, the 
markup does not hold the expansion, it just says e.g. 
<acronym>NFS</acronym> but does not include what it needs to expand to. 
We could add an attribute but then it would only appear if the attribute 
is present. Shall we expand all occurrences (would mean lots of 
redundancy) or just the first? Other idea would be to use a separate XML 
database of acronym expansions, install it with the docs and let 
JavaScript rewrite the acronyms. But in this case we have to think of 
how to handle acronyms that can have multiple expansions.

Gabor