Re: GDP: consistency in @q @qq @samp @code

[Graham Percival]

(I'm CCing this back to -devel.  Kurt: if this causes problems for you, 
feel free to remove the -devel CC when you reply.)


Kurt Kroon wrote:
> On 10/9/07 11:46 PM, "Graham Percival" <address@hidden> wrote:
> > In that case, I don't think that @samp{cresc} (as in "@samp{crescendo}
> > is often abbreviated as @samp{cresc.}") is appropriate.
>
> According to the HTML spec, SAMP "designates sample output from programs,
> scripts, etc.". The "sample output" is what makes this the most appropriate
> way to mark up this information (assuming that @samp{...} becomes
> <samp>...</samp> in the HTML output.
>
> If displaying the content in a fixed-width font is the only downside, that
> can be modified easily -- as long as you have access to the style sheet:

We have the style sheets, so that's not a concern.  However, this isn't 
ideal, since I'd like to be able to write
        The @samp{~} symbol denotes a tie.

Longer input would definitely use @code, but I agree with Werner that 1- 
or 2-char input should use @samp.

> >  I see three possibilities:
> >
> > - @var{cresc}: prints it in italics
>
> "an instance of a variable or program argument"?
>
> Okay, the italics are nice ... and I can see the reasoning, sort of:
> "crescendo is the argument that the program ... err ... musician uses to
> generate a steadily increasing volume".

Actually, the reasoning was simply "I want it to be italics, but I don't 
like using @emph".  :)

You can see a list of all the commands here:
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Marking-Text.html
(in particular the 9.1 indicating)

Also note that we produce docs in PDF and info as well, so I'd rather 
not rely on changing the style sheet.


> I'm not completely convinced ... but I'm not that enamored of @samp, either.

I'm not convinced either, but we need to pick _something_.  @var isn't 
exactly what we want, but it's the best option I've seen so far.

@dfn{} is a possibility, I suppose... actually, when looking at how 
these commands look in info, @dfn is probably better.

> > - @q{}: normal text inside single quotes.
>
> Meh -- doesn't convey much additional information.

It's used mainly in the tutorial... although most of these instances 
should be turned into @dfn  (if we go that route).


> (And yes, working with HTML and CSS, and thinking about semantic/structured
> markup are part of my "real" job.)

Great!  You're probably more qualified than me in this discussion, then.  :)

Cheers,
- Graham