docs/78240: Replace <literal> with <quote> around a #

[Giorgos Keramidas]

Tom Rhodes <trhodes at freebsd.org> wrote:
>Marc Fonvieille <blackend at freebsd.org> wrote:
>>Marc Fonvieille wrote:
>>>> Yep.  I mean, we use literal everywhere else.  There shouldn't
>>>> really be a reason to quote the specific character.
>>>>
>>>> In all honesty, I guess it depends on how you look at it.
>>>
>>> In fact I was wondering about a typographic rule, I was wondering if
>>> people used to put quotes cause they could not "emphasize" the
>>> character via any rendering.  I just looked at a (french)
>>> typographic book, it seems (nothing is stated) they use quotes for a
>>> single character, on another typographic book no quotes...  I will
>>> reread them on tomorrow morning.
>>
>> Ok, here's the usage I found in the French "Imprimerie Nationale"
>> rules ("Lexique des r?gles typographiques" ISBN 2-7433-0482-0):
>>
>> - most of time use of italic for a character
>> - sometimes use of quotes (in fact for more than 1 character)
>>
>> I looked for American typography usage but on Internet it's not easy
>> to find reliable information.  If someone owns the book "The Elements
>> of Typographic Style" by Robert Bringhurst (ISBN: 0881791326)...
>>
>> In fact it's often obvious that on a printed version using a specific
>> rendering (italic, tt, etc.) is better for the reader, on an online
>> version this may be different.  I wanted to see what do O'Reilly, so
>> I looked at at "DNS and BIND" (4th Ed.) expecting to find an answer,
>> but I was disappointed they were not really consistent.  Most of time
>> they use italic (for a word or a term it's always italic).  For a
>> single character they use both italic and quotes, in fact it seems
>> they use quotes when the italic version of the character does not
>> exist or is "ugly"?  For example they used ``@'' and
>> <italic>&</italic> (but also <italic>*</italic>).
>>
>> Well to sum up, I did not find a good answer.

Good summary, Marc.  Thanks for taking the time to do this :-)

> Let's just wrap it in <emphasis> and have done with it?

I like my bikesheds painted black, please :P

Seriously, folks...  Please, let's not make a hasty decision that will
impact the style of current and future FreeBSD documentation in a
negative manner, by compromising for something less than "professional".

The summary Marc wrote is very good.  Since this is an issue of how text
should be presented, I think we should keep the <literal> element only,
and work on the way this is presented to the reader through style/dsssl
changes.  This way we can keep marking up text in a way that makes the
structure of the document apparent _and_ present the output to the
reader in any way we see fit.

For instance, in PS/PDF output we may use simple fixed-width text for
literal stuff.  Many books that I've read (even online books) use the
following typographic conventions:

	 Typeface or Symbol      Meaning
	 ------------------      ------------------------------
	 Fixed-width             The names of commands, files,
	                         and directories; screen output
	                         and program listings.

	 Bold/Semi-bold          What a user types on his terminal.
	 fixed-width

	 Italics                 Replaceable elements, titles of
                                 cross referenced sections, mild
                                 emphasis, titles of books or other
                                 bibliographic stuff.

	 Bold                    Emphasized text, section titles,
                                 new words, misc. important terms.

For other formats, we may have to use a different style:

- ASCII text output cannot use italics or bold, so we may have to employ
  some form of quoting (automatically inserted by the stylesheets).

- HTML output that depends on italic/bold/underline looks ok in GUI
  browsers, but may look awfuly in elinks, links, lynx or w3m.

I think, after having said all this I may have to learn DSSSL and put my
patches where my mouth is, but I couldn't resist posting :P

Giorgos