development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-08-27 03:29:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

State correct usage of literal examples in man pages in the coding standards

Browse source 
The man pages contain inconsistent usage of backticks vs. single quotes
around options, commands, etc. that are in paragraphs. This commit states
that backticks should always be used around literal examples.

This commit states that "--" and friends should not be escaped
(e.g. use `--pretty=oneline` instead of `\--pretty=oneline`).

This commit also states correct usage for typesetting command usage
examples with inline substitutions.

Thanks-to: Ramkumar Ramachandra <artagnon@gmail.com>
Thanks-to: Stuart Rackham <srackham@gmail.com>
Thanks-to: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Jason St. John <jstjohn@purdue.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jason St. John 2013-11-14 18:08:45 -05:00 committed by Junio C Hamano
parent d7d2c87955
commit ca03c3682a
1 changed files with 31 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
Documentation/CodingGuidelines
View file

@ -244,9 +244,11 @@ Writing Documentation:
Every user-visible change should be reflected in the documentation.
The same general rule as for code applies -- imitate the existing
conventions. A few commented examples follow to provide reference
when writing or modifying command usage strings and synopsis sections
in the manual pages:
conventions.
A few commented examples follow to provide reference when writing or
modifying command usage strings and synopsis sections in the manual
pages:
Placeholders are spelled in lowercase and enclosed in angle brackets:
<file>
@ -296,3 +298,29 @@ Writing Documentation:
Use 'git' (all lowercase) when talking about commands i.e. something
the user would type into a shell and use 'Git' (uppercase first letter)
when talking about the version control system and its properties.
A few commented examples follow to provide reference when writing or
modifying paragraphs or option/command explanations that contain options
or commands:
Literal examples (e.g. use of command-line options, command names, and
configuration variables) are typeset in monospace, and if you can use
`backticks around word phrases`, do so.
`--pretty=oneline`
`git rev-list`
`remote.pushdefault`
Word phrases enclosed in `backtick characters` are rendered literally
and will not be further expanded. The use of `backticks` to achieve the
previous rule means that literal examples should not use AsciiDoc
escapes.
Correct:
`--pretty=oneline`
Incorrect:
`\--pretty=oneline`
If some place in the documentation needs to typeset a command usage
example with inline substitutions, it is fine to use +monospaced and
inline substituted text+ instead of `monospaced literal text`, and with
the former, the part that should not get substituted must be
quoted/escaped.