Help talk:Style/Migration to new Code formatting templates

From ArchWiki
< Help talk:Style
Revision as of 12:56, 15 October 2011 by Kynikos (Talk | contribs) (split from Help talk:Style)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Months have passed since the initial proposal to restyle the Code formatting templates, references can be found here:

The new templates are Template:Ic for inline code, Template:Bc for block code and Template:Hc for block code with header.

A possible migration strategy could be the following:

  • Cli -> space-initial lines or Bc
  • Codeline -> Ic (merge some use cases like command names into a generic monospace template without background?)
  • Command -> space-initial lines or Bc
  • File -> Hc
  • Filename -> Ic (or keep Filename? see also #Template:Filename) (or merge in a monospace template without background?)
  • Kernel -> Hc
  • Cursor -> deprecate?

As discussed initially on #Do not use <pre> for one-liners, we could also copy the current Template:Bc to Template:BHc, and restyle Template:Bc to look like <pre>, thus deprecating the use of <pre>. [implemented]

Another related discussion: #Prepare examples of both simple and advanced use of the (new) wiki templates & formating.

Please share your ideas. -- Kynikos 12:50, 21 September 2011 (EDT)

Usage guidelines

Maybe it's better to define the rules based on the various usage examples, so here's a possible starting point (this is the simplest implementation, it only uses 3 templates):

Simple commands

Use Template:ic for inline code: # lspci . Use Template:bc for block code:

# lspci 

-- Kynikos 21:51, 29 September 2011 (CEST)

[discuss here...]
+1 for this, it fits in well with the other styling we use (unlike {{Cli}}) and having the overflow scrollbars on everything would be nice (I guess it could be added the the site stylesheet though). thestinger 17:52, 8 October 2011 (EDT)
overflow:auto is already bundled both with bc and hc ;)
code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code
code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code
code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code
-- Kynikos 19:39, 8 October 2011 (EDT)
Commands with response

Use Template:bc:

# iwconfig

lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0

-- Kynikos 21:51, 29 September 2011 (CEST)

Of course this method would replace Template:Command, and we'd lose the difference between command and output even at source level, so the change would be irreversible.
As an alternative, Template:Command could be restyled like this:
# command
output
But this way we'd need also an output-only template:
output only
-- Kynikos 09:13, 5 October 2011 (EDT)
...just thinking that this would then pose a problem of coherence, in fact we'd have Template:bc for both file and cli code, but a different template for command output: there wouldn't be any reasons left to avoid making also a proper template for file code...
To sum up, the current alternatives are:
  • the 3-templates way (Ic, Bc, Hc)
  • the 6-templates way (Ic (all inline code1), Bc (cli commands), Cc (cli commands with output), Oc (command line output only), Fc (file content), Hc (file content with heading))
    1As a chain effect this method could also lead to a similar differentiation in inline code...
-- Kynikos 09:36, 5 October 2011 (EDT)
I think we should just stick to the 3 templates - having lots of them is just confusing and they won't be used consistently. hc and bc can replace pre/command/file.
iwconfig
lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0
/etc/rc.conf
VAR=whatever
#!/bin/rm
thestinger 18:14, 8 October 2011 (EDT)
If I have to be honest, I wanted to avoid using Template:hc to replace Template:Command because I don't like the incoherence between your example and the simple:
# iwconfig
In this example, # iwconfig appears on light blue, but in your example it appears on dark blue if also its output is shown.
I also prefer having just a few templates, but I'd like to propose a 4th and last template to replace Command:
# iwconfig
This is probably the only real problem that's left to be solved in the whole guide.
-- Kynikos 19:34, 8 October 2011 (EDT)
(This new template would be used with something like {{oc|input|output}}).
Note that pointone agreed about the color incoherence in User talk:Pointone/Code Formatting Templates.
-- Kynikos 19:55, 8 October 2011 (EDT)
This is a demo with a dashed line instead of solid:
Template:Oc
-- Kynikos 20:12, 8 October 2011 (EDT)
The last example with a dashed line looks great and is far more intuitive than separating the command and output by background color. ~ Filam 11:52, 10 October 2011 (EDT)
Ah good to see that somebody actually likes it :) I'd like to read more opinions though, come on people ^^ -- Kynikos 16:02, 10 October 2011 (EDT)
One of my primary goals of this template reformation was to simplify the system by reducing the number of templates. I believe that only three code formatting templates are necessary: inline, block, and block + header. If consistency is key, I would suggest replacing Template:Hc with Template:Oc as shown above.
Template:Oc
Template:Oc
I prefer the solid line over dashed... but this is but a minor concern. -- pointone 18:39, 10 October 2011 (EDT)
What about this compromise? (currently implemented in Template:Sandbox)
{{hc|filename|content}}:
/file/name
{{hc|input|output|}} (just append a pipe to change into input/output mode):
# command
-- Kynikos 19:59, 10 October 2011 (EDT)
Couldn't resist to make a dashed-line version, which I admit I like more. (currently implemented in Template:Oc)
{{hc|filename|content}}:
Template:Oc
{{hc|input|output|}} (just append a pipe to change into input/output mode):
Template:Oc
-- Kynikos 20:10, 10 October 2011 (EDT)
Ah, note that Template:Command is used less frequently than Template:File, that's why I chose it to be the "altered" version of this template. -- Kynikos 20:15, 10 October 2011 (EDT)
Changing direction completely, I've tried to improve the current implementation of the guidelines, adding:
  • When in the need of representing both command line input and output, still use {{bc|code}}, but make sure to separate the input code from the output with an empty line, even if the actual output does not print it [...]
Clear and simple. I'd like to know if thestinger still doesn't like it. About my observation that we'd lose the distinction between input and output in the source code, would it be such a bad thing? IIRC there are already examples of input and output being represented in the same <pre> block, and I don't dislike them, really.
-- Kynikos 11:51, 11 October 2011 (EDT)
File content

Use Template:ic for inline code: IgnorePkg=kernel26.

Use Template:bc for block code:

[core]
# Add your preferred servers here, they will be used first
Include=/etc/pacman.d/mirrorlist

[extra]
# Add your preferred servers here, they will be used first
Include=/etc/pacman.d/mirrorlist

[community]
# Add your preferred servers here, they will be used first
Include=/etc/pacman.d/mirrorlist

Use Template:hc for block code with file name in header:

/etc/fstab
# <file system>        <dir>         <type>    <options>             <dump> <pass>
none                   /dev/pts      devpts    defaults                0      0
none                   /dev/shm      tmpfs     defaults                0      0
 
/dev/cdrom             /media/cd     iso9660   ro,user,noauto,unhide   0      0
/dev/dvd               /media/dvd    udf       ro,user,noauto,unhide   0      0
/dev/fd0               /media/fl     auto      user,noauto             0      0
 
LABEL=Arch_Linux       /             ext4      defaults,noatime        0      1
LABEL=Arch_Swap        swap          swap      defaults                0      0

-- Kynikos 21:51, 29 September 2011 (CEST)

If Template:hc is used only for file content we could prepend "File: " to the heading, as in Template:File, and it could be moved to Template:fc. -- Kynikos 09:17, 5 October 2011 (EDT)
At the moment I've added an optional 3rd argument which defaults to "File: ". -- Kynikos 13:28, 8 October 2011 (EDT)
File names

Use Template:ic for inline file names: /etc/pacman.d/mirrorlist.

See also #Template:Filename.

-- Kynikos 21:51, 29 September 2011 (CEST)

I think this would be both consistent with the other new templates and more readable. Same for command names and other names. 1+ -- Roygbiv 16:25, 6 October 2011 (EDT)
I really like the new templates, and I think they look much better than the existing ones. The only gripe I have though is that file and path names won't stand out as much from other commands and monospaced text which really helps the reader when skimming articles or trying to parse vague or difficult to comprehend paragraphs with lots of various commands and paths in it. As such, I am strongly requesting that there be a separate template for file and path names where the only difference between it and the current Template:ic is a different font color (e.g. like how the current Template:Filename is only different from Template:Codeline via green font color). -- Jstjohn 21:18, 9 October 2011 (EDT)
Can you point to an example article which would really benefit from such a distinction? Theoretically, paths should already be easily distinguishable from commands, variable names and so on even at a glance, without the need for a different font color.
One of the purposes of reformatting the templates was to try and simplify the template system, and I don't know if having 2 different inline code templates would be of so much help. What's more, if we make that distinction, why shouldn't we use other colors for the other various kinds of monospaced strings that can appear in the text of an article?
To sum up, I'm in contrast with this idea, but the discussion is open and more opinions are welcome and will be taken into account. Just remember that this guide will be a compromise, it will not make everybody happy: as we've acknowledged also in other discussions, there will never be complete agreement over style issues among the users.
I'd also remind that James Eder was in favour of keeping Template:Filename in #Template:Filename, so I think currently we are 2 vs 2 :)
-- Kynikos 16:49, 10 October 2011 (EDT)
I don't think the distinction between command and file/path name templates is important. I think the distinction should be made clear through both context and consistent inclusion of the full path when referring to a file/path.
The policy of always including the full path is useful in itself, for reducing ambiguity and eliminating the need to look up where the file/directory is supposed to reside.
I realize sometimes people include the full path when referencing a command, but I think this wording is easily avoided.
Examples: "use the bar command, found at /etc/foo/", or, "add the following line to the /etc/foobar file".
Basically the slashes and wording should indicate a file or path, while no slashes means a command.
I always found the Template:Filename template hard to distinguish on my screens, so I don't mind getting rid of it. | Emiralle 18:23, 10 October 2011 (EDT)
As I commented above regarding command output, I want to reduce the number of code formatting templates. I cast my vote against Template:Filename and for using Template:ic for everything. -- pointone 18:51, 10 October 2011 (EDT)
@Emiralle: I don't think such a policy will be necessary. Rewording your own example, in "use the /etc/foo/bar command" the code part technically is both a file path and a command path, so I don't see a problem in using it and it wouldn't confuse me at all. -- Kynikos 19:18, 10 October 2011 (EDT)
Command names

Use Template:ic for inline command names: makepkg.

-- Kynikos 21:51, 29 September 2011 (CEST)

[discuss here...]
Other names

Use Template:ic for other inline names (e.g. variables): PATH.

-- Kynikos 21:51, 29 September 2011 (CEST)

[discuss here...]

Prepare examples of both simple and advanced use of the (new) wiki templates & formating

so users can easily figure out how to get what they need and not get stuck with ugly stuff like this: Template:Cli

I've added <nowiki> tags and it already looks better:

Template:Cli I'm not sure if this idea belongs in the Style Guide and if the new templates will need much explaining :-) -- Karol 13:31, 9 May 2011 (EDT)

I'm not correcting edits like that, because I have faith the Age of the New Templates will come :P -- Kynikos 13:07, 10 May 2011 (EDT)
I too shall eagerly await its arrival ;P -- Karol 13:42, 10 May 2011 (EDT)

Template:Filename

Is Template:Ic going to replace also Template:Filename? -- Kynikos 09:18, 19 September 2011 (EDT)

My opinion: I like current Template:Filename usage as it is currently. I would, however, like to see other templates and other HTML tags migrated to Template:Ic and Template:Bc. That is, of course, once they are no longer "in development" (nudge, nudge). James Eder 20:37, 19 September 2011 (EDT)
Eheh those templates are in development because they're waiting to be enforced together with this very article, I also prepared some sort of a migration procedure some time ago in User:Kynikos/Random formatting ideas#Upgrade_procedures although it'd need heavy upgrading itself.
Waiting for more responses about Template:Filename, default is not replacing it. I am a bit undecided on this, because replacing it would go in the direction of simplicity, and it would be coherent with the decision not to distinguish between cli and file text in block code templates; on the other hand I've never been very convinced by that decision, so that's why I'm asking for opinions.
-- Kynikos 05:52, 20 September 2011 (EDT)
Can summarize what we do and do not have a consensus on here? The migration process seems to be fairly straight forward it just needs to be said which templates we are sure about. Is Template:Filename the only one left undecided? James Eder 13:06, 20 September 2011 (EDT)
There has never been an official discussion on this, so I'm creating #Migration to new Code formatting templates. -- Kynikos 12:50, 21 September 2011 (EDT)

Template:Cursor

Deprecate Template:Cursor? -- Kynikos 16:35, 29 September 2011 (EDT)

Yes, please! -- pointone 18:42, 10 October 2011 (EDT)
Done. -- Kynikos 08:18, 11 October 2011 (EDT)

<nowiki> templates?

Consider creating Template:bc2 and Template:ic2 that include <nowiki> tags. Or, perhaps Template:bc and Template:ic include <nowiki> tags and Template:bc2 and Template:ic2 can be used if wiki formatting is desired (i.e. unformatted text is more often the desired outcome). (Taken from User:Pointone/Code Formatting Templates) -- Kynikos 16:35, 29 September 2011 (EDT)

I played around with this last week and failed; may not be possible. -- pointone 13:10, 4 October 2011 (EDT)
Kk, I've tried {{#tag:nowiki|{{{1}}}}} out of curiosity but it doesn't work how I expected, I guess we can close this one: if there were a way to do this, it would be an easy one. -- Kynikos 18:15, 4 October 2011 (EDT)

Darker background?

Use a slightly darker background for code templates to increase its visibility? Compare current color with
darker color
. -- Kynikos 16:35, 29 September 2011 (EDT)
<opinion>I would prefer to defer to the underlying style sheet and our web designer (i.e. match <pre>). Consider filing a bug report/feature request to fix the style, instead.</opinion> -- pointone 18:47, 10 October 2011 (EDT)
True, it will be much cleaner. However I'll do it when we'll have started using the new templates, so he can better judge the effects of the new style. -- Kynikos 19:08, 10 October 2011 (EDT)

Bugs?

Lists or indentation
  • header
content

Use an outer div to enclose both header and content? (not working needed) -- Kynikos 16:35, 29 September 2011 (EDT)

Fixed, removed offending line break in source code. -- Kynikos 17:45, 6 October 2011 (EDT)
Font weight

Main Page.

Main Page I make the text in the link appear in normal weight.

Not investigated yet. -- Kynikos 16:35, 29 September 2011 (EDT)

What if, instead of using <pre> in Template:ic, we used a <span> formatted with font-family: monospace;? -- Kynikos 16:50, 29 September 2011 (EDT)
(of course setting also background-color, and padding if needed (on an inline tag??)). -- Kynikos 17:55, 29 September 2011 (EDT)
Fixed, and yes, padding is allowed on an inline tag, and it doesn't affect line height. -- Kynikos 17:14, 6 October 2011 (EDT)

inline-block?

What about using "display:inline-block;" for Template:ic? It would allow easy triple-click selection of the whole code. Yes, that way the span's padding (0.2em) would affect line-height, but we can fix that with "margin:-0.2em 0;" (perfectly standard and supported by css-standard-compliant browsers, negative margins are not a dirty hack). -- Kynikos 05:39, 7 October 2011 (EDT)

Implemented, after all this template was originally using display:inline-block. -- Kynikos 12:03, 7 October 2011 (EDT)