Gentoo Wiki talk:Guidelines

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.

Update the guidelines to provide links to other gentoo pages in article titles

Talk status

This discussion is still ongoing.

Please share your opinion to: https://wiki.gentoo.org/index.php?title=Gentoo_Wiki:Guidelines&diff=744154&oldid=730098&rcid=&curid=1325

-- Kreyren (talk) 15:02, 27 October 2018 (UTC)

To Brian Evans (Grknight) :
I understand that you agree with the change? https://wiki.gentoo.org/index.php?title=NVIDIA/Optimus&diff=744114&oldid=744112&rcid=&curid=42197 -- Kreyren (talk) 15:06, 27 October 2018 (UTC)

The way Discussion is provided so that graphic designers like me can rest in peace

Talk status

This discussion is still ongoing.

I suggest to change the way we make discussion to be more effective as `All articles should have "Troubleshooting"` for example meaning syntax likeː

== TITLE == {{talk|open}} ̥Stuff to say and cry about. --~~~~ '''Discussion Hereː''' --~~~~ blah.. blah.. blah.. --~~~~ blah.. blah.. blah.. ...

(Look at source)

Can we possibly make this into a template? <3 --Kreyren (talk) 21:29, 13 September 2018 (UTC)

All articles should have "Troubleshooting"

Talk status

This discussion is still ongoing.

Based on previous experience and end-user feedback gathered from Discord Gentoo i strongly believe that all articles should have "Troubleshooting" section with stub (if less then 3 sub-sections are provided) so that end-users can resolve their issues without the need to visit 3rd party website and which encourage more ppl in contributing to solution.

--Kreyren (talk) 21:11, 13 September 2018 (UTC)

Discussion Hereː

In fact wiki articles have already troubleshooting included f.e. nginx, nfs-utils, tac_plus. Some articles are to short for troubleshooting, but if they get bigger it might get troubleshooting. Some articles do not need a troubleshooting section at all. In my opinion SHOULD HAVE is too much for all articles. Better is MIGHT HAVE, or something like to encourage autors to create a troubleshooting section, but it does not fit to all wiki articles. Troubleshooting should stay optional and is very welcome. Needle (talk) 19:22, 11 October 2018 (UTC)

The blueprints have already troubleshooting included Gentoo_Wiki:Article_Blueprints/Software. Needle (talk) 19:38, 11 October 2018 (UTC)

Heading text

Usage of KernelBox

Talk status

This discussion is still ongoing.

Isn't it better to provide path instead of using {{KernelBox}} ? Based on my experience it's very missleading. I would prefer to use this version instead https://imgur.com/a/emX22W2 in one line of text with "some" formatting to differenciate it for end-user.

Possibly like? {{KernelBox| Device Drivers -> Multimedia support -> Media Controller API (MEDIA_CONTROLLER [=y])}}

KERNEL

 Device Drivers -> Multimedia support -> Media Controller API (MEDIA_CONTROLLER)

NOTE: won't display with `[=y]` parameter. --Kreyren (talk) 03:09, 29 August 2018 (UTC)

Discussion:

Long time ago only was discussion about do write an extension for mediawiki to show setting for different versions of kernel. And maybe also do show in config mode like

.config

CONFIG_BLA=y
CONFIG_BLA_DEV=m

If you able for this, please do it. --Cronolio (talk) 05:54, 29 August 2018 (UTC)

--Kreyren (talk) 13:25, 3 September 2018 (UTC)

Shouldn't be an issue, but i need the permission from gentoo dev.

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:

Users have no indication where the destination points. It could be a inappropriate site or some other place they don't want o visit.
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 Sven Vermeulen (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)

Gentoo Wiki talk:Guidelines

Contents

Update the guidelines to provide links to other gentoo pages in article titles

The way Discussion is provided so that graphic designers like me can rest in peace

All articles should have "Troubleshooting"

Heading text

Usage of KernelBox

Shortened URLs

Var element

Update linking section to include 'limited' linking

Use of Cmd versus Invocation

Bold titles

Package missing

See also template and article description properties