Re: Style issues for conventions page - Mailing list pgsql-www

On 21 May 2013 09:18, Greg Smith <greg@2ndquadrant.com> wrote:
> A documentation comment came in that highlights a weird situation with the
> web version of the documentation.  Check out
> http://www.postgresql.org/docs/current/static/notation.html for a moment.
> In the PDF documentation, this example looks just like it reads.
>
> There are a few problems with the web version though:
>
> -The word italics in "emphasized in italics" is actually bold.  The source
> code for that is <emphasis>italics</>.
>
> -"emphasized in bold face (example)" shows an example that is neither bold
> or italics.  Source for that one is (<emphasis
> role="bold"><literal>example</></>)
>
> I don't know that anything in the source needs to change, but something in
> the HTML generation pipeline seems off here.

The terms that are supposed to be "emphasized in italics" need
different HTML rendering.  In the documentation they appear as:

<i class="FIRSTTERM">term</i>

This markup is no longer welcome in today's world of descriptive
markup and separate CSS styles.  And the text on the conventions page
uses:

<span class="emphasis EMPHASIS c2">italics</span>

Both of these should be using <em> HTML tags, with no need for classes
(unless that "c2" is supposed to mean something?)  This would give
descriptive context to the text and would automatically render it
correctly as <em> renders in italics as per the HTML spec.

So the <emphasis> SGML should simply convert to <em> in HTML, which is
clearly a more natural and equivalent markup.

And with:

"On occasion, parts of program code are emphasized in bold face
(example), if they have been added or changed since the preceding
example."

with "example" using:

<span class="bold EMPHASIS c4">example</spam>

I can't find any evidence that such formatting is used in this way.
I've looked through many pages where I might expect to see this in
action, but there's no attempt to use such formatting anywhere that I
can find.  Is anyone able to show where this is actually used?  Bold
text is certainly used for replaceable text in syntax definitions, but
such text is also in italic.  The boldness of such text is acquired
through the non-descriptive "c2" class, and the italic through the
"REPLACEABLE" class, but only the italic aspect is covered by the
conventions page with regard to placeholder text.  And those examples
use the <tt> HTML tag, which is deprecated as of HTML5 anyway, so
ideally should be changed to something with more of a future, such as
<span> which wouldn't need any accompanying CSS modification.

In any case, to format the bold example text as bold on the
conventions page, we could just add a CSS rule in docs.css:

.bold { font-weight: bold;
}

But I'm not convinced that the description of when bold text occurs is true.

--
Thom