Wikipedia talk:Manual of Style/Computing (failed proposal)/Archive 1

Archive 1

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)

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 indispensable 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)

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)

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)

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)

Font size of <code> blocks

First, let me say that I find the use of x-height to set the font size rather peculiar. Yes, it's standard-compliant CSS, but it doesn't make a whole lot of sense (the font-size parameter sets the height of the font bounding box, the relationship of which to the x-height is not consistent across different fonts). Instead, I replaced the 3ex value with 125%. It's less confusing and it achieves the same effect.

However, I object to setting the font size manually altogether. If you have difficulty reading text at the default font size, then you need to adjust your browser settings. If there is a consistent problem with the default settings on most users' browsers, then it should be taken up with Wikipedia administrators so that a modification can be made to the style sheet for the whole site (after all, if it is a problem, it's not unique to just this page). —Kbolino (talk) 19:04, 21 January 2009 (UTC)

MoS naming style

There is currently an ongoing discussion about the future of this and others MoS naming style. Please consider the issues raised in the discussion and vote if you wish GnevinAWB (talk) 20:54, 25 April 2010 (UTC)

RFC: restructuring of the Manual of Style

Editors may be interested in this RFC, along with the discussion of its implementation:

Should all subsidiary pages of the Manual of Style be made subpages of WP:MOS?

It's big; and it promises huge improvements. Great if everyone can be involved. Noetica^Tea? 00:31, 25 June 2011 (UTC)

Semantic markup

This entire thing is badly outdated, and needs to be updated to use proper Semantic HTML, since MediaWiki (including Wikipedia's installation of it) now properly supports the semantic code markup elements, and we have convenient templates for them. An example like the following from the wikisource of the guideline:

$ ls [''options''] [''file'' ...]

Needs to be recoded as:

<code>{{samp|$}} ls [{{var|options}}] [{{var|file}} ...]</code>

both of which look like:

$ ls [options] [file ...]

but the latter markup has some subtle differences (color of prompt is actually grey), and more importantly can be parsed and acted upon by software, independently styled (e.g. custom syntax highlighting in user stylesheets), and so forth, while the former is basically indistinguishable from any misc. text strings. See documentation at Template:Var and the "See also" items it links to ({{samp}}, {{kbd}}, etc.)

I can take on the conversion unless someone else wants to do it. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 00:34, 16 August 2011 (UTC)

I wonder if these markups would be too noisy and complex (too many {curly brackets} flying around and awkward 1=escaping of equals = signs), which would discourage editing. I wouldn’t want an article to become like an intricately complicated template. For example in theory I’d like more use of small caps, but Template:Smallcaps says to avoid it if possible, citing WP:MOS#Keep markup simple, which I also support. The beauty of the apostrophes for bold and italics is they don’t interfere a great deal with the rest of the wiki text.

 Having said all that I’d like to keep an open mind; maybe see how bad it is in practice. Are there any other discussions on this sort of thing?

 Also, your {{samp|$}} template for the prompt has spacing around it which is disconcerting in a block of monospaced text.

 Vadmium (talk) 13:11, 21 August 2011 (UTC).