Gentoo Wiki talk:Guidelines

From Gentoo Wiki
Jump to: navigation, search
Note
This is a talk page. Please add newer comments below older ones, and sign your comments using four tildes (~~~~). When adding a new section (at the bottom of the page), please mark it as "open for discussion" by using {{talk|open}} so it will show up in the list of open discussions.

Please discuss all changes here before making any changes to the Guidelines article.

Go to this article's archive sub-article to see previous completed discussions.

Shortened URLs

Talk status
This discussion is done.

Recently a discussion in #gentoo-wiki occurred on shortened URLs. I believe it is in the best interest of the Gentoo community to not permit shortened URLs for a few reasons:

  1. Users have no indication where the destination points. It could be a inappropriate site or some other place they don't want o visit.
  2. The link could be used for tracking purposes. Something that really should't be happening unless the user makes the decision to actually travel to a destination server (meaning there's not a third party in the middle intercepting the request).

In fact, it would seem our spam filter already blocks some shortened URLs. I make the proposition of adding a new section to the Guidelines that will outlaw shortened URLs. --Maffblaster (talk) 20:38, 29 November 2016 (UTC)

I agree with you. Valid shortened URLs should be expanded before adding them to the Gentoo wiki. Fturco (talk) 10:33, 30 November 2016 (UTC)
Same here, no need for shortened URLs in the wiki. --SwifT (talk) 18:57, 30 December 2016 (UTC)

Var element

Talk status
This discussion is done as of December 30, 2016.

I see the <var> element is being used on this wiki for (the names of) configuration variables like "USE", "CONFIG_PROTECT", etc. I'm not sure I like this usage. I think of <var> as marking text that is itself variable (IOW, "replaceable" or "stand-in" text).

Examples:

eselect locale set VALUE   (<var> within a <code> element)
man command   (<var> within a <kbd> element)

Note that <var> formats text in italics on probably all graphical browsers. This is the convention also used in many published computer books for such stand-in text.

I guess the current usage is probably too entrenched to change at this point, but I'm curious if anyone else shares my concern about this. - dcljr (talk) 23:45, 10 August 2016 (UTC)

The use of <var> can be for both variables themselves (in mathematical expressions or programming) as well as for placeholders, according to w3.org's information. So I don't mind the use of the <var> entity for both.
The formatting as a result of the use of <var> is something that I also find less than optimal, but differentiating variables from the regular text is a good thing. If we find a better expression for such variables, we can easily replace all occurrences of <var>USE</var> with something else later.
I would not appreciate to make it direct links to pages explaining the variable in more detail. We should only link when appropriate, and repeating the same link is also something I dislike (and is not used on wikipedia either for instance).
--SwifT (talk) 09:25, 10 November 2016 (UTC)
I think using the <var> tag to define variables themselves makes sense on our wiki. Once the reader knows italic text means variable, they can more quickly read though the article with the right concept in mind. --Maffblaster (talk) 19:07, 30 December 2016 (UTC)

Update linking section to include 'limited' linking

Talk status
This discussion is done as of May 3, 2017.

I would like to update the linking section a bit (the one currently titled with HTTPS for external links). My suggestion would be to

  • change the title to "Linking"
  • expand it to have users only use linking to other articles or resources once (or, in large articles, once per main section)

This is also used by wikipedia.

--SwifT (talk) 09:44, 10 November 2016 (UTC)

Yes, please! I agree wholeheartedly. I probably should have had a discussion here before adding the HTTPS for external links section. :( --Maffblaster (talk) 08:16, 11 November 2016 (UTC)
As of a few seconds ago I have implemented the change. 6 months is long enough to wait for it. :) --Maffblaster (talk) 23:57, 3 May 2017 (UTC)

Use of Cmd versus Invocation

Talk status
This discussion is done as of November 13, 2017.

Recently, a new set of templates (Invocation and RootInvocation) were added to the Gentoo Wiki to allow expandable output for commands. As an example, consider the following:

user $cat --help
Usage: cat [OPTION]... [FILE]...
Concatenate FILE(s) to standard output.

With no FILE, or when FILE is -, read standard input.

  -A, --show-all           equivalent to -vET
  -b, --number-nonblank    number nonempty output lines, overrides -n
  -e                       equivalent to -vE
  -E, --show-ends          display $ at end of each line
  -n, --number             number all output lines
  -s, --squeeze-blank      suppress repeated empty output lines
  -t                       equivalent to -vT
  -T, --show-tabs          display TAB characters as ^I
  -u                       (ignored)
  -v, --show-nonprinting   use ^ and M- notation, except for LFD and TAB
      --help     display this help and exit
      --version  output version information and exit

Examples:
  cat f - g  Output f's contents, then standard input, then g's contents.
  cat        Copy standard input to standard output.

GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
Full documentation at: <http://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'

versus

user $cat --help
Usage: cat [OPTION]... [FILE]...
Concatenate FILE(s) to standard output.

With no FILE, or when FILE is -, read standard input.

  -A, --show-all           equivalent to -vET
  -b, --number-nonblank    number nonempty output lines, overrides -n
  -e                       equivalent to -vE
  -E, --show-ends          display $ at end of each line
  -n, --number             number all output lines
  -s, --squeeze-blank      suppress repeated empty output lines
  -t                       equivalent to -vT
  -T, --show-tabs          display TAB characters as ^I
  -u                       (ignored)
  -v, --show-nonprinting   use ^ and M- notation, except for LFD and TAB
      --help     display this help and exit
      --version  output version information and exit

Examples:
  cat f - g  Output f's contents, then standard input, then g's contents.
  cat        Copy standard input to standard output.

GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
Full documentation at: <http://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'

I have noticed some edits that switch existint Cmd and RootCmd usage to Invocation and RootInvocation. I suggest to add in the guidelines that Invocation and RootInvocation should only be used when the output is very verbose and more exemplary in nature rather than important for the reader to use directly. Its primary purpose (hence the name) is to show command invocation information (the --help output).

Regular commands and their output should, imo, remain with Cmd and RootCmd. One of the reasons I see is that users who might print out an article, or export to PDF or ePub to read elsewhere, will not view the output anymore. So let's save some trees and only use Invocation when it makes sense ;-)

--SwifT (talk) 18:49, 30 December 2016 (UTC)

Agreed. Please implement your suggestions here into the Guidelines. --Maffblaster (talk) 23:59, 3 May 2017 (UTC)
Somewhere on mediawiki site i seen note abot that expand/collapse may not work on some mobile devices. So lets no put important text in command output --Cronolio (talk) 17:02, 8 June 2017 (UTC)
Right, the {{Invocation}} templates are simply to provide users with a quick web-reference of the help output from a command. Users can get the same information locally on their machine after they install the program and run the appropriate invocation for help. I have also added a parameter to the normal {{GenericCmd}}, {{Cmd}}, and {{RootCmd}} templates for expanding/collapsing output (see collapse-output). So now we have options. --Maffblaster (talk) 22:04, 17 July 2017 (UTC)
Closing this discussion as SwifT has not responded in 6 months. I think things are in a good state as of now. I'd like the {{Invocation}} templates to still be used for invocation, as we'd be able to explicitly summarize commands with invocations using properties at some point in the future. For all other verbose output the plan is to use {{GenericCmd}}, {{Cmd}}, and {{RootCmd}} with the collapse-output parameter. --Maffblaster (talk) 17:50, 13 November 2017 (UTC)

Bold titles

Talk status
This discussion is done as of July 17, 2017.

The Wikipedia convention of bolding the first appearance of the article's title in the lead section has crept into some of our articles. Should this be encouraged or discouraged? - dcljr (talk) 11:25, 20 February 2017 (UTC)

I honestly don't mind either way. If the article is referencing and acronym, I'd like the acronym described in bold near the beginning of the article. That's my only input on bold text. Kind regards, --Maffblaster (talk) 00:01, 4 May 2017 (UTC)
Just guess, to add a bit more information on what I've been doing recently... I've been using the {{c}} template in the introduction paragraph instead of the bold. I only do this when the intro contains a mention of the command-line executable. I guess if the article doesn't mention the command-line executable bold is being used, which is fine by me. --Maffblaster (talk) 19:15, 15 June 2017 (UTC)
Any feedback from you, Dcljr ? --Maffblaster (talk) 18:39, 17 July 2017 (UTC)
Not really, no. - dcljr (talk) 21:42, 17 July 2017 (UTC)

Package missing

Talk status
This discussion is done as of July 17, 2017.

I missed {{Package| }} on the page --Jonasstein (talk) 06:55, 30 May 2017 (UTC)

There is a line at the end of Block-level layout elements that contains a mention of the {{Package}} template. --Maffblaster (talk) 19:16, 15 June 2017 (UTC)
Since that mention links back to the table of inline templates, I've gone ahead and added {{Package}} to that table. - dcljr (talk) 21:56, 17 July 2017 (UTC)

See also template and article description properties

Talk status
This discussion is still ongoing as of July 17, 2017.

Using SMW properties to define the Article description property in various articles, I've created a new {{See also}} template that can be used to reduce the need to re-describe every article summary in the See also sections of the articles. Any objections to mentioning the See also template and defining how to set the article description property here? Kind regards, --Maffblaster (talk) 18:38, 17 July 2017 (UTC)

Bump. Any comments? My only concern is how the {{See also}} template will play out with translations. --Maffblaster (talk) 17:46, 13 November 2017 (UTC)
I don't have any objections to describing this template in the guidelines. Please do. (I can't say anything about translations.) - dcljr (talk) 05:09, 4 December 2017 (UTC)