Culture: Language: Punctuation
Special characters for do-not-use-quotes   (+2, -1)  [vote for, against]
It is borderline “let’s all”, but still useful

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)
-- kbecker, May 29 2004

This might be more useful if some arbitrary text occurs inside the command, eg:
mount -t auto (your device) (mount point)
-- Detly, May 29 2004


But then if you wanted to show ">>" (without the quotes) you'd have to write <<>>>> which just looks confusing.
-- hippo, May 29 2004


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.
-- benjamin, May 29 2004


<< & >> are used by the French as quotation marks proper.
-- Knut, May 29 2004


Would an XML based version work better?

<phrase> tar –cfx /dev/rs0 </phrase>
-- silverstormer, May 29 2004


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, <#> ... </#>?
-- kbecker, May 29 2004


//XML already uses all the single letters//

What, all of them?
-- Detly, May 29 2004


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.)"
-- jutta, May 30 2004


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?
-- krelnik, May 31 2004


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.
-- engineer1, Jun 01 2004


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.
-- Detly, Jun 01 2004


as [Knut] points out, the French have already invented this.
-- neilp, Jun 01 2004


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.
-- kbecker, Jun 02 2004


In that case, go with the:

text to type in

On its own line.
-- GenYus, Jun 02 2004


having text on it's own line is great unless you have trailing or leading spaces.
-- neilp, Jun 02 2004


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... """"""""
-- phundug, Nov 03 2011


tar -cfx /dev/rs0

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

rm -rf /
-- mouseposture, Nov 03 2011



random, halfbakery