h a l f b a k e r yThe mutter of invention.
add, search, annotate, link, view, overview, recent, by name, random
news, help, about, links, report a problem
browse anonymously,
or get an account
and write.
register,
|
|
|
In many technical documents for software you find phrases like:
Enter: “tar –cfx /dev/rs0” (without the quotes)
I know what is meant, but the phrase “(without the quotes)” is still tedious, and I know people who were confused. Some authors of manuals have been tinkering with bold or italic,
but those are also just crutches. The idea is to use a dedicated pair of characters to describe quotes that the reader of an instruction should not use when entering commands. For backward compatibility the characters should be part of the plain ASCII set, like “<<” and “>>” (without the quotes).
Once people are used to these characters it will be much easier to read software documentation and I won’t get phone calls like “I entered “tar –cfx /dev/rs0”, but the response was “unknown command”” (without the outer quotes)
[link]
|
| |
This might be more useful if some arbitrary text occurs
inside the command, eg:
mount -t auto (your device) (mount point) |
|
| |
But then if you wanted to show ">>"
(without the quotes) you'd have to write
<<>>>> which just looks confusing. |
|
| |
Using an alternate colour makes it pretty easy to follow, even without explanation. Colour screens are quite common already; when colour printing becomes cheap then those that like distributing documents on wood can do the same. |
|
| |
In monochrome textual situations, like email or the halfbakery, putting:
what to type
...on its own line is hard to beat. |
|
| |
<< & >> are used by the French as quotation marks proper. |
|
| |
Would an XML based version work better?
<phrase> tar –cfx /dev/rs0 </phrase> |
|
| |
For compatibility with existing fonts an XML style quotation should work. That way the world doesn't need to steal anything from the French and people can still take quick notes by hand. It should be something shorter than <phrase> though. As far as I know XML already uses all the single letters so it would have to be a less used character, <#> ... </#>? |
|
| |
//XML already uses all the single letters// |
|
| |
There are already plenty of XML tags with a connotation of "literal text". For example (in "docbook" alone), <literal>, <quote>, and <userinput>. |
|
| |
Normally, typewritten font and indentation are used to express input that the users are supposed to just type, with cursive letters for words that are meant to be replaced by something else. Is there anything wrong with this convention that you're trying to fix? |
|
| |
If you're following through on your threat of making people write XML, you'll need an easier way of writing "(without the stuff in angle brackets, and &#NNN; means an ISO-8859-1 character with that decimal value, and here's a list of common other &word; abbreviations and what they mean.)" |
|
| |
I'm with [jutta] on this one, I always use a fixed-pitch (typewriter-style) font and/or a different color or indentation for this type of stuff, it seems to work well. |
|
| |
As for XML, isn't that what the tag <CODE> is for? |
|
| |
i could be being a little slow and stupid here but shirley a more obvious solution would be to edit the program such that "tar -cfx /dev /rs0" works as well with or without the quotes. an alternative would be for a command that is within quotes to produce a an error message containing the incorrect code, just copy and paste the bit between the quotes. |
|
| |
Certain quotes can mean certain things. In Linux, if you
type something between backquotes (`) in the middle of
some shell command, it means "do what's in the
backquotes, and substitute it back in." Also, sometimes
quotes are used to distinguish between input as text and
input as filename. It would probably cause more problems
than it solves, but it's a good thought. |
|
| |
as [Knut] points out, the French have already invented this. |
|
| |
The problem with pitch and colors is that you need the right kind of software and printer. A typical problem I have is a database at my work place where people store solutions they found for the more tricky questions. To save space the database only saves plain ASCII and replaces <tab> or multiple <space> with just a single <space>. Many databases used in call centers do that. It can lead to real confusion. |
|
| |
In that case, go with the: |
|
| |
having text on it's own line is great unless you have trailing or leading spaces. |
|
| |
Type the command "print 2 + 2" but without the quotes and without the phrase "but without the quotes and without the phrase "but without the quotes and without the phrase "but without the quotes and without the phrase "but without the quotes and without the phrase "but without the quotes and without the phrase "but without the quotes and without the phrase "but without the quotes and without the phrase "but without the... """""""" |
|
| |
Arguably, someone who needs to
be told to omit the quotes has no business using a
command like
that. And would such a person be familiar with
the
"do-not-use quote" convention? |
|
| |
I thought this was going to be special quotes for
things like |
|
| |