Wikipedia talk:Manual of Style (command-line examples)

From Wikipedia, the free encyclopedia

I have created this page to help writers of articles documenting commands and such to maintain a clean, professional look (and to make them easier to read and understand!). Any information that is incorrect or inaccurate and any guideline here presented that is inconsistent with Wikipedia I implore you to correct.--Kbolino 02:18, 4 Mar 2005 (UTC)

Contents 1 Boldface for User Input 2 All capitals in DOS program names 3 DOS prompt 4 Providing comprehensive information, i.e. listing all options

[edit] Boldface for User Input

Disagree with "The entire command line should be boldfaced, to distinguish it from the output." Bolding has very specific meaning on articles, and it is a bad idea to try and overload it. Neither are your input lines emboldened when you input, so it's not useful to mirror it. The input line is distinguished from the output by the placement of the generic prompt character. Dysprosia 04:26, 9 Mar 2005 (UTC)

I can see your point. Without boldface, it might also be necessary to indicate the use of only one command-output pair within one example. The use of multiple commands and their output will quickly become confusing.—Kbolino 07:23, 11 Mar 2005 (UTC)

I submit that a debate about whether to boldface the user input in a command-line example, to distinguish it from system prompts and system output, is a first step toward debate about whether to highlight the syntax in the command-line example. Syntax highlighting is a popular feature in text editors. Most programmers would probably consider syntax highlighting to be indispensible for making computer code easier to understand. Similar ergonomic advantages may result from highlighting the syntax in a command-line example. That is, to determine what is appropriate in an encyclopedia article, one should consider not only the appearance of a CLI text in a terminal window, but also the appearance of similar text in a text editor. Teratornis 14:48, 12 June 2006 (UTC)

Before we limit ourselves to the CLI's formatting of user input, let's not forget the part we unavoidably omit: the person who reads an encyclopedia article does not type the input. The typical command-line interface does not bold the user's input because, presumably, the user can recognize what he is typing, or what he just typed, and distinguish it from system output. A CLI is not a system for documenting its own use, nor for explaining to third parties what some other user did in a previous session. That is, the design goals for the CLI are different than the design goals for an encyclopedia, and the default formatting that the CLI presents to a (presumably expert) user may not be ideal for explaining the user's session to passive readers. Since readers do not type the input text interactively the way the original user did, they lack the same functional cues and can benefit from bolding of the input text.

DocBook (a documenting tool designed by and for professional technical writers) has a <userinput> element specifically to format the user's input in command-line examples; DocBook stylesheets typically present <userinput> text in boldface. I think it's an obvious improvement in clarity, especially for extended examples with multiple lines of user input interleaved with system output. I would prefer to follow the DocBook stylesheet default, and bolding the user input in command-line examples (particularly in extended examples with multiple lines of user input). Teratornis 19:28, 11 June 2006 (UTC)

A nice feature of DocBook is that it separates logical markup from presentation. It would be nice if the Wiki software let us do that here: we could mark up the various components of command-line example text according to what they are (system prompts, user input (perhaps further dividing it into command names, options, parameters, and shell metacharacters), and system output), and then ideally the reader could decide whether and how to highlight the syntax: either all the same as plain text, or with the various parts in different styles and/or colors. Teratornis 03:57, 12 June 2006 (UTC)

What you suggest is not wholly impossible. The problem lies (in my opinion) with the inability to use custom stylesheets (or perhaps some functionality to append certain style rules to the style sheet as the browser sees it). That is, the functionality could be provided through the use of the class and/or id attributes:

<span class="cli_prompt">prompt</span> <span class="cli_input"><span class="cli_input_cmd">command</span> <span class="cli_input_opts">options</span> <span class="cli_input_params">parameters</span></span>
<span class="cli_stdout">The output of the command, as printed to the stdout stream</span>
<span class="cli_stderr">An error message as printed to the stderr stream</span>

Yeah, just had a total braindump there. Way too much markup. I think I'm a little dizzy, but I imagine you get the picture. In the meantime, I'll make the user input bold.—Kbolino 11:52, 16 November 2006 (UTC)

[edit] All capitals in DOS program names

I may have written it, but I no longer feel that DOS program names should be presented in all-uppercase. It is, in my opinion, counter-intuitive. It also might be appropriate to leave out the extension. Shell commands are a different matter, though.—Kbolino 11:30, 16 November 2006 (UTC)

[edit] DOS prompt

The default prompt for DOS contains the working drive or directory (depending on version). This page, as it stands, says to use > alone as the prompt, but that may be counterintuitive and lead people to type the > character. I would like to suggest changing it to use C:\> or C>. --Random832(tc) 18:13, 7 February 2007 (UTC)

[edit] Providing comprehensive information, i.e. listing all options

In my humble opinion, it seems to be counter productive to not provide all options to commands. Many man pages are not only poorly formated, written in a style making it difficult to understand and without examples.
When, someone comes to wikipedia, should they be sent away with a comment : look elsewhere. Or even worse sent to a link describing what a man page is. This is not what the visitor is even looking for.

The listing for the ls command is an example of a "send them away" attitude.

ls has a large number of other options (see: man ls).

Clicking on this link sends the visitor to a page that has nothing to do with the ls command.
I would like to reinsert the detailed list of options, but will wait for a while for a response.
Thank you all for providing a great resource.
I hope to assist in making it better.
Sincerely,
DGerman (talk) 18:10, 18 January 2008 (UTC)