Zsh Mailing List Archive
Messages sorted by: Reverse Date, Date, Thread, Author

Re: INSTALL changes

On 10/10/2014 02:14 AM, Peter Stephenson wrote:


Your attitude to this is precisely what I had hoped. Final edit is of course up to you.

One further comment:
If we're going to have quotes around literal strings e.g. option names
they ought to be more consistent with the rest of the
documentation... unfortunately a lot of the (minor) edits here render
them inconsistent.  However, we're by means 100% consistent anyway.
Generally, it's not clear to me the changes in quoting here make things
better, e.g. quoting Perl, which with the capital is a name as it
stands, but not 'PDF' or 'TeXinfo' or '.info', doesn't seem particularly
useful; c.f. 'configure' which is a normal word so quoting when it's
used as a programme is useful.  So I'd be inclined to leave these alone
until we generally have more clarity on how to do this (that's our lack
of clarity, not Ray's) --- or maybe just keep the changes that obviously
make things clearer like the 'configure' one.  Getting wide agreement on
something this minor is nearly always impossible anyway!  So I wouldn't
like to get in the way of many obviously useful changes.

It might indeed seem like a minor thing, but trying to get some regularity in this 'quoting' is worth doing. I applied my style to the document, but this is very much open to debate. Myself, I use double quotes mostly for actual text that might be typed verbatim into some file, and single quotes (never using the abominable back-tick ;-) for 'things' or commands or file names or just to indicate that a word is being used in some way that is not 'normal':

'cd' to the '/etc' directory, then execute 'nano fstab' and add the line: "mount -t auto /dev/fd0 /mnt/floppy" to the file. Then save it and reboot by hitting 'ctrl+alt+delete'.

Maybe right about 'Perl'. Why bother? it is already a proper noun. Perhaps only because in the context of a technical document, it can sometimes be unclear how a word is being used:

'make' is the command that will build your program. Don't make any mistakes using it.
Perl fishers are known to enjoy using 'Perl' on their computers.

Right about '.info' and 'PDF' ... by my rules they should be quoted.

I generally only quote the first instance of the use of a program name per paragraph. After that it's tedious to keep doing it.

Perhaps commands to be typed literally should also be in double quotes:

Is it pointless to quote the name of a variable like '$PATH'?

Type: "cd /etc <ENTER>" then: "nano fstab <ENTER>" ....

Really, clarity is the only rule that matters.

Messages sorted by: Reverse Date, Date, Thread, Author