discuss: style questions
Subject:
Re: style questions
From:
David Merrill ####@####.####
Date:
12 Jul 2001 21:20:08 -0000
Message-Id: <20010712172001.G4340@lupercalia.net>
On Thu, Jul 12, 2001 at 08:55:24AM -0700, ####@####.#### wrote:
> Converting TeTeX-HOWTO from LinuxDoc, I have a few
> questions...
>
> * The title is "The teTeX HOWTO: The Linux-teTeX Local
> Guide". Should this be shortened to "teTeX-HOWTO" like
> every other HOWTO has?
Every HOWTO has two names, really. That's probably a bug, but it's how
things are atm. There's the actual title, and there's the short title
based on the filename. Some of our listings use short title
(e.g., Net-HOWTO) and some use long (e.g., Linux Networking HOWTO).
Keep both of these in mind.
However, that title is still long and unwieldy imho. I'd suggest
`teTeX HOWTO' and leave it at that. But...
We have no standard for whether or not to use `The' and/or
`Linux'. So, we could call it `The Linux teTeX HOWTO' or `Linux teTeX
HOWTO' or `teTeX HOWTO' or even `The teTeX HOWTO. This is a problem
that makes it difficult to find documents sometimes. Can re all reach
a consensus on a recommended naming convention? Remember that not all
of our HOWTOs are Linux specific, but some are.
> * usernames: I'm using (using brackets for tags to be
> nice to browsers)
>
> You must be logged in as [Literatal
> remap="tt"]root[/Literal] to etc etc.
Please use all lowercase in your tags, as that will translate to XML
and your usage won't.
> Is this right?
I won't answer that part because I'm not sure.
> * When to use Command and when to use Application? For
> instance:
>
> Now [?]ls[/?] the directory and see your results.
>
> You must have [?]metafont[/?] installed for this to
> work.
This *should* be documented in the LAG. [command] applies to command
line utilities and other `tools' but [application] applies to larger
works, including most (if not all) GUI tools, e.g., KWord or
Evolution, and some console programs such as vi or emacs.
You must exercise judgement here, but IMO if it has no UI it is a
command. If it does, it's an application.
> * What about internal commands specific to the
> program? I'm using Command for TeX commands, but it
> renders them as bold, which is not what I was
> envisioning (I was thinking typewriter face). Example:
>
> Use the [?]\spiffy[/?] command to spiff up your
> document.
Not sure. DocBook: TDG says `command -- The name of an executable
program or other software command'.
> * Is there a point to replacing all instanced of 'TeX'
> with '[Application]TeX[/Application]'?
>
> * Is it a hard-and-fast rule that examples run in a
> shell should start with 'bash#' or 'bash$'?
You can use an entity. I've never done it, but someone else will
surely explain it to you.
> * Are LaTeX documentclasses and packages 'Command's?
> 'Token's? Example:
>
> Use the [?]letter[/?] documentclass when you want to
> write a letter.
>
> You'll have to install the [?]pstricks[/?] package to
> include EPS graphics.
Don't know. Not commands, I don't think, but I don't know what they
wuold be. Maybe just literals and leave it at that?
Sorry I couldn't give definitive answers on all these, but I tried.
Others here know DB better than I.
Regards,
--
Dr. David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Collection Editor & Coordinator http://www.linuxdoc.org
How many Win95 bugs did Microsoft admit to fixing in Win98? Over 3,000? What
kind of amateur-hour design and testing process lets 3,000 bugs slip
through?
--Paul Somerson, PC Computing
