Improved Phobos dox

[Jacob Carlborg]

On 2013-09-16 18:22, Andrei Alexandrescu wrote:

> [citation needed]

http://en.wikipedia.org/wiki/Semantic_HTML

> On the contrary, from what I've read in LaTeX and typography is that you
> want to keep formatting semantics high level, e.g. "This is a chapter
> title" as opposed to "this is heading text" or (worse) "this is large
> text with large spacing".

This is not LaTeX. When using the proper tags you're adding semantic 
meaning to your content. Example, a proper table with an header and 
footer should look like this:

<table>
   <thead>
     <tr>
       <th>Header</th>
       <th>Header 2</th>
     </tr>
   </thead>

   <tfoot>
     <tr>
       <td>Footer data</th>
       <td>Footer data 2</th>
     </tr>
   </tfoot>

   <tbody>
     <tr>
       <td>Data</td>
       <td>Data 2</td>
     </tr>
   </tbody>
</table>

The reason for adding proper tags like "thead", "tfoot" and "tbody" is 
it gives semantic meaning to the content. A browser can choose to scroll 
the content in "tbody" while having the content in "thead" and "tfoot".

The same idea can be applied to navigation as well. Using the "nav" tag 
a browser could probably choose to scroll the main content and but not 
the content of the "nav" tag.

> It is, but it seems to me the more specific "list of symbols introduced"
> is better.

Then you add a class in addition to the correct tag.

> In this case the distinction is actually material because we have one
> style file for both Phobos and the larger dlang.org, and we may want to
> format regular <dd> differently from Phobos symbols description. This
> seems to be a Good Thing (tm).

Then you use different classes, but still uses the correct tag.

Another example. If you want to emphasis text one uses the "em" tag, not 
the "i" tag. The it's up to the style sheet (CSS) to decide if the 
emphasized text should be italic, bold or some other font.

It's the same thing why one should use the type "bool" (D, C++) instead 
of "int". It gives the correct semantic meaning.

> Actually as I noted above that's an issue because we share the same
> style file between dlang.org and phobos. Of course, we could have two
> files, but I don't find using classes a shameful alternative.

We most likely should.

-- 
/Jacob Carlborg