Gentoo Wiki:Suggestions

Feel free to add suggestions for our Wiki on this page. To add a new topic, click on the "Add topic" page tab. Remember to sign your suggestion with --~~~~, or the "Signature and timestamp" button in the editor toolbar. See Help:Signatures.

Archive

For completed discussion see Archive subpage.

Relationship with existing Gentoo documentation

Talk status

	This discussion is still ongoing.

Will it be possible to somehow incorporate the existing Gentoo documentation into this wiki, perhaps have this as the user editable version, with revisions pushed to the guidexml docs with are the official "reference" and are verified to be of a certain quality by the documentation team. --Mark alec 13:53, 26 September 2011 (UTC)

I agree. This would relieve Gentoo Documentation from a majority of documentation, such as GCC Upgrade is a good example (although this upgrading has been resolved). This would also provide Gentoo users more recent and up-to-date documentation. The only documentation I see as toss-up, are the Gentoo Install documents and Ebuild Writing documents -- which should remain standardized. However, the pro with going Wiki on these, the Gentoo Documentation group would only need to take a snapshot of a current wiki -- similar to Gentoo and Sabayon or System RescueCD. ;-) This is really long over due, but not too late! Signed: Roger 19:00, 15 November 2011 (UTC)

Keep in mind, that the doc team is not interested, see ML column at Gentoo Wiki:Progress#Content / Scope

Astaecker 19:14, 15 November 2011 (UTC)

It isn't about being against anything. License-wise, this should be okay, since the current license in use by the majority of documents is the same, just a lower version. From the legal document of the CC-BY-SA, it mentions something about allowing later versions so I believe that we can use the content of the gentoo documents and put it under the 3.0 version on the wiki. I also don't mind that this is done, but for a documentation development point-of-view, keeping the master in a wiki might not be a best option. There is quite some documentation development being done off-line (used to be even more offline than online, but things change ;-) I would personally rather see more specific documents be moved from the main site to the wiki (such as the logcheck one).

--SwifT 17:11, 26 December 2011 (UTC)

/start rant

Okay, I am new to the Gentoo project and the conflicting/outdated documentation is driving me crazy, specifically all the X.org stuff only using nvidia-drivers and I apparently have to use nouveau since nvidia-drivers don't support GeForce2 according to some documentation, and I came across one document that said that it does support it. I could probably use the man pages, but the docs are supposed to make setup easy. There are a few other examples, but that one is the biggest.

/end rant

So, since there is no apparent page to explain this, I have set up a (hopefully) temporary "inconsistency-/differences-between-versions page" for the Documentation just before I wrote this comment. I am just posting to draw attention to it and let people know that it is there.

post scriptum ad persona de Gentoo/Documentation: please, PLEASE, use this page to edit documentation -- Preceding unsigned comment by User:Jamiahx

The wiki is not a bug/improvement tracker for the documentation, file bugs on bugs.gentoo.org instead. I deleted the article. Also, please sign your comments in the wiki. Thanks, —a3li 20:52, 31 March 2012 (UTC)

If you don't know which driver to use, what you should do is ask on the Gentoo Forums, and once you have the answer, edit the wiki. For official documentation, file a documentation bug. If there is a discrepancy in the wiki, it's probably better to add it to its Talk Page. (Although I think having some consistent way of reporting problems in the wiki like you outlined is a good idea) --Alec 20:58, 31 March 2012 (UTC)

The talk page is the canonical page to raise problems with an article. Or, this page if it's a concerning multiple articles. —a3li 21:13, 31 March 2012 (UTC)

I think the only thing still holding us back a bit for moving most documentation to the wiki would be the need for translations. If there is anything that I can help with to find a way of supporting translations on the wiki, I'd love to hear it. --SwifT (talk) 06:39, 15 March 2013 (UTC)

Template for Elements in Troubleshooting Sections

Talk status

	This discussion is still ongoing.

Troubleshooting sections on g-w.org just get larger and larger, and it is very difficult to tell when the information in them is still useful.

I propose a {Troubleshooting} template which clearly shows:

• Date reported
• Date report was last useful
• User reporting (allow +1's if possible)
• Link to bugzilla
• (Problem description)

For example:

{Troubleshooting|2011-10-15|2011-10-25|bgo=366141|Screen all black|blah blah blah}

gives something like:

== Troubleshooting ==
=== Screen All Black ===
First Reported: 2011-10-15
Reported by: [hangfire]
Last Seen: 2011-10-25 {Note|If this information is useful, please
update this field!}
Bugzilla Link: [link]

blah blah blah

The bugzilla field should support links to other bug trackers (such as bugzilla.kernel.org when it comes back) Hangfire 22:05, 25 October 2011 (UTC)

This one might be a bit tricky as the +1 function needs actual code to back this. Maybe you can browse the MediaWiki Extension list [1] to see if anything offers a similar functionality? Also for this one, please add it to the suggestions page, and if you can, start working on example templates or ask for help with that. At any rate, I support the idea. User:a3li

[1] http://www.mediawiki.org/wiki/Category:Extensions

I remember the old g-w.com(before the big wipe) had a {{bugzilla}} which you where supposed to weave into the narrative like you do with {{Note}} or {{Warning}}. IIRC it went something like {{Bugzilla|You might get a shock when you fiddle with a spoon inside the toaster|#bugzillaid}}. /Ni1s 22:13, 25 October 2011 (UTC)

• Hmm, lets let bugzilla do what it's suppose to do, however, Bugzilla Reports seems to be promising for our wiki needs :)mitri 03:30, 27 October 2011 (UTC)

• Made a template in User:Wimmuskee/Troubleshooting, used in LTSP. Wimmuskee 13:37, 17 December 2011 (CET).

Machine Specific Articles

Talk status

	This discussion is still ongoing.

Would it perhaps be a good idea to have a reference article for articles dealing with a specific laptop/desktop/whatever model? These articles on g-w.com really lack consistency. /Ni1s 18:35, 25 October 2011 (UTC)

---

My email to wiki@gentoo.org:

One feature of g-w.org are the machine-specific pages, which (ideally) have the cpuinfo, lspci and kernel config each for an individual model of desktop / laptop.

The best of these is a fantastic resource - for each piece of hardware, it has a link to a full article explaining how to properly set it up, with short paragraphs with machine- specific quirks and workarounds. These pages are invaluable when buying a new machine, where getting concrete information on processors / cards /chipsets etc. can be really hard to find. eg. http://en.gentoo-wiki.com/wiki/Acer_Aspire_Revo_R3600_/_R3610 (One of mine :toot:)

The worst of these is a horrendous mess, needing {{Wikify}}, with loads of partial information explaining hardware that is already properly explained in full and specific articles. cpuinfo and lspci information is incomplete (or does not cover all variants), and there is loads of useless content (such as full copies of xorg.conf). They are a mess, are generally unmaintainable (or unmaintained) and are not helpful. eg. http://en.gentoo-wiki.com/wiki/Acer_Aspire_3002WLMi

It is really important for the official wiki that machine-specific pages are allowed (as they can be so useful), but that authors are constrained (encouraged!) to write 'good' articles, with many links to properly-maintained information and without useless, replicated partial-guides that go out of date without anyone noticing.

Thus, we need a template or similar to show what is and what is not encouraged in these articles. {Template:Computer} or {Template:Machine} would be good names. Additionally, these would be a good candidate for a separate Category. Hangfire 21:53, 25 October 2011 (UTC)

I never understood why whole ls(cpu|pci|usb) dumps would be useful. Why not split it up(use -s?) under some useful wired, wireless, bluetooth headings. /Ni1s 22:18, 25 October 2011 (UTC)

I suggest a 'big table' approach, e.g. http://de.gentoo-wiki.com/wiki/HP_Compaq_6715b . Astaecker 07:35, 26 October 2011 (UTC)

Pros:

• Compact table to easily determine the support status (see Status column).
• Links in the first place to properly-maintained articles.
• Workaround informations possible through Note (german: Hinweis) column.
• Except of workarounds no maintaining needed.

Contras (in comparision to above solution):

• No 'one-page' guide. Answer: It 's not possible to put all informations of the properly-maintained articles in a 'one-page' guide. It's too much.
• Big table edits are not user friendly. Solution: We can create an template for that big table, e.g. {{Computer}}

I created an example {{Computer}} template and an example computer article using it. --Astaecker 07:01, 4 December 2011 (UTC)

I would suggest a solution based on templates. As an example take a look at IP stack. So you just insert {Nvidia} to get a few paragraphs or a table with all the info about the GPU, or perhaps something like {GPU:Nvidia} or even {HW:GPU:Nvidia:model#} - so it would be more like a library with descriptions - just point out to the right direction. Pros: easy to maintain in single place. Cons: templates could be difficult to setup, and would require conscious and precise separation of info between templates.
:)mitri 03:52, 27 October 2011 (UTC)

In favor of the 'big table' approach, a use case is already present in ASUS_M50V, with the addition of creating links to page headings below where applicable (and lose the TOC), see HP_Compaq_t5710. Excess /proc/cpuinfo can be prevented by putting it in predefined templates, so they can be reused in different pages (see User:Wimmuskee/Processor/TransmetaEfficeonTM8000. Also in favor of a clear template structure, and explanations, for the computer pages, and predefined hardware templates.
Wimmuskee 9:09, 03 December 2011 (CET)

Not if favor of the 'big table' approach here. Pimping a suggestion here, the Asus Eee 901 article on gentoo-wiki. Feature(by hardware) headings with nifty tricks weaved in. Bit of old(maybe outdated) cruft there but you get the idea, and a good idea is to use transculated pages wherever we can./Ni1s 22:35, 3 December 2011 (UTC)

Perhaps a combination by generating the transcluded pages from the big table, see User:Wimmuskee/Computer/example./Wimmuskee 16:20, 04 December 2011 (CET)

So any conclusion? --Emc 08:26, 10 July 2012 (UTC)

No. Because there was no discussion on the topic. Also no one started a vote.

I worked in the meantime on my 'big table' {{Computer}} template and documentation. There's now a real example article - Dell Latitude D630 D830 - , linking to the needed hardware articles.

Astaecker 20:19, 10 July 2012 (UTC)

I created a comparison table of the since now proposed solutions. Astaecker 11:29, 27 July 2012 (UTC)

name	notes	Pure Big table	Sections by templates	Big table + sections	sections
author, proponent		astaecker	Dmitri	Wimmuskee	Ni1s
example article		Dell Latitude D630 D830	IPstack	User:Wimmuskee/Computer/example	Asus Eee PC 901
devices overview	An overview at the top for quick orientation	Yes	TOC	Yes	TOC
status overview	An overview at the top for quick orientation	Yes	No	Yes	No
lspci, lsusb, etc. output		Yes (model column)	No	Yes	Yes
setup infos	kernel config, packages, configuration	Links to properly-maintained articles	Links to properly-maintained articles	Links and device sections	Device sections
Complete setup infos	Additional infos: advanced configuration, addon software, troubleshooting	Part of properly-maintained articles	Part of properly-maintained articles	No (or task of the author)	No (or task of the author)
quirks	Workarounds for non-standard setup	Yes (set a note and add a quirk section)	No	Yes (in device section)	Yes (in device section)
All-in-One page	All setup infos on one page	No	No	Yes	Yes
template per device	Use of well-defined device specific templates	Yes (templates for each row)	Yes (templates for each device)	Yes (templates for each row and device)	Partial (templates for each device)
maintenance	of the Computer article	status, quirk sections, (linked articles)	device templates, (linked articles)	status, device templates, device sections, (linked articles)	device sections

'Link' template for translated pages

Talk status

	This discussion is still ongoing.

{{Link}} solves a problem with linking to translated pages, see the Rationale section. I would like to have some feedback before moving the template in the Template namespace. Astaecker 15:19, 29 October 2011 (UTC)

would [[Special:MyLanguage/Kernel|Kernel]] do the same trick? :)mitri 22:58, 29 October 2011 (UTC)

Yes, but only if you're logged in and set your language in the preferences. In every other case - e.g. you're are just visiting to read an article (not logged in) - [[Special:MyLanguage]] defaults to english. Astaecker 06:40, 30 October 2011 (UTC)

Templates need to be localized

Talk status

	This discussion is still ongoing.

Text formatting templates, such as Template:Note or Template:Warning, need to be either automatically localized, or need standard localized versions (e.g. something like "Template:Note/ru" or "Template:Примечание") available for translators to insert manually. — tetromino 19:22, 11 November 2011 (UTC)

I experimented with it. Some solutions:

• Separation of code and text by using subpages. The templates can be protected and translators can still update the text in the subpages.

• For automatic localization using subpages I found no way to address the subpage (relativ or absolute) inside the template to fetch the translations, because after transclusion all variables ({{BASEPAGENAME}}, etc.) apply then to the target page.
• Translate the text (and only the text) with the translate extension works, but the <translate> tags around the text of the original english template will get transcluded and displayed in the target page. No problem with translated templates. Works too for english pages, if we use the english localized template version ({{Template/en}}).

• Translate the text without the translate extension we can use for each text string a parameter. The localized template version calls main template, passes through all parameters and add the translated text parameters.
• No separation. The template gets big and the code is harder to read.

• Automatic localization means, all translations are in the template. Technically we can use a switch function and e.g. User:Astaecker/Lang subpage template to detect the wanted language.

I prefer the "translate extension" solution, because of the quality control of the translations. --Astaecker 11:08, 12 November 2011 (UTC)

Success Stories

Talk status

	This discussion is still ongoing.

A new category in which users can put their machine configuration.

It is nice to divide docs by hardware/software, but seeing a complete working machine of people is something that makes things much clearer. --Alonbl 23:51, 12. Nov. 2011 (UTC)

Print to PDF and/or Export to EBook File Format?

Talk status

	This discussion is still ongoing.

I prefer reading long articles on my EBook Device (Kindle DXG). Seeing most documents being published in PDF, or some sites even providing EBook formats. Thankfully, my device can handle PDF but some can't. As for the Amazon Kindle's, I've seen really good results using kindlegen on converting EPUB to MOBI, but using kindlegen on HTML with TABLE TAGS produces poor MOBI files. As such, I usually use PDF files for computer technical documents. Also, kindlegen (aka mobigen) is binary only (proprietary). A couple months ago, I mirrored the entire Gentoo Documentation just to convert XML to HTML using gorg, and then kindlegen to convert to MOBI. This is very tedious for EBook users! I manage quite well as I use the console, but avoid Calibre due to it's package bloat and lack of command line only. (Calibre requires X for it's command line tool.) Probably the simple solution for now, for simple articles would be to ensure a 'Print to PDF' option. Lengthy articles such as the Gentoo Handbook and EBuild/EClass documentation, would be nice to have an EBook format. Signed: Roger 19:09, 15 November 2011 (UTC)

I second this motion as far as PDF and ePUB goes. I even submitted a wish/bug to Gentoo's Bugzilla about this. ----Hook 00:14, 24 March 2012 (UTC)

Provide direct links to Help:Formatting and Gentoo Templates on Edit Page

Talk status

	This discussion is still ongoing.

When editing a page, I always go stumbling along trying to find a dumb template or how to format something as the direct links to these pages are not always published on the page I'm editing. Except for the basic "Help" link, which doesn't do much good. How about placing at least two of the most popular Help pages (Help:Formatting and Gentoo Templates) right on the page that is being edited by a user so he/she doesn't have to waste time trying to hunt them down. (Although by now I have most of Help:Formatting memorized, some of Gentoo Templates are new.) The full links follow.

• Help:Formatting Pretty much memorized here, but a good one for most others!
• Special:PrefixIndex/Template: I think this is the one?
• Help:Gw.com_cheat_sheet Actually, this is more what I'm talking about compared to the 2nd one above as it's more structured (easier read) like the Help:Formatting page! Lacks many of the templates/commands though.

Signed: Roger 19:09, 15 November 2011 (UTC)

Definition of Macros

Talk status

	This discussion is still ongoing.

Dear wiki-admins,

You should define some macros as soon as possible for things like referencing portage packages, infoboxes for software that autocomplete from portage information, general infoboxes for software that include fields such as 'deprecated by', and create categories for each of the Gentoo projects (Hardened, etc.) so that relevant articles can be grouped together in a way that makes sense for users coming from other sources of documentation.

Voltaire 00:02, 2 August 2012 (UTC)

We will definitely also need one for man pages. Like 'man 5 corosync.conf' should be possible to define with a quick macro that makes it obviously possible to type at the terminal but also clickable in-wiki to go to a hosted, HTML version of the man page. This should be the latest version auto-built out of portage, or preferably a diffed history of versions. This sort of cross-linking is precisely where a lot of Linux documentation falls down and where the Gentoo community could showcase its pragmatism. Voltaire 00:30, 4 August 2012 (UTC)

Template documentation rework

Talk status

	This discussion is done.

I reworked all templates and its documentation to get some improvements. As an example see {{Error}}.

1. Testcases (/testcases subpage):
   1. Add testcases for every parameter (using {{Testcase}}.
   2. Put testcases, which are for debugging only (e.g. checking for mandatory parameters) in <noinclude>-tags, so they will not be transcluded.
2. Documentation (/doc subpage):
   1. Add consistent headings (Parameters, Usage, See also)
   2. Fill out the missing pieces (intro description, parameter description, etc.)
   3. Transclude the /testcases subpage to showcase the usage of the template.
3. Template:
   1. Check for mandatory parameters and print an error message (using {{Error}}).
   2. Put the whole template code in <includeonly>-tags, so you don't see the often ugly template visuals. As each template page transcludes the /doc and so the /testcases subpage, the showcasing testcases of the /testcases subpage are seen also on the template page.

Any comments? - Astaecker 14:58, 9 August 2012 (UTC)

As there is no feedback, I will update all templates next week. Astaecker 04:57, 19 August 2012 (UTC)

Done. Astaecker 08:54, 24 August 2012 (UTC)

"desc" parameter for templates Code, File, Kernel

Talk status

	This discussion is still ongoing.

The templates {{Code}}, {{File}} and {{Kernel}} are users of {{ContentBox}} and use 1. unnamed parameter to add a description and the 2. unnamed parameter to add the actual content. The problem is, that the 1. unnamed parameter is optional, so you always have to specify an empty parameter.

I suggest to move the description part to a new "desc" parameter and change the content part to the 1. parameter. The 2. unnamed parameter should show an {{Error}}.

I know, this means a lot of changes to existing articles, but IMHO it is the right thing to do in the long run. Astaecker 09:27, 24 August 2012 (UTC)

Template for generic inline code

Talk status

	This discussion is still ongoing.

I looked Help:Gw.com_cheat_sheet and it seems we don't have a proper way to add generic inline code. Gentoo-wiki.com uses a specific template called Codeline, and we also have something similar, but for another purpose: the Path template. In my opinion using ''foo'' is not correct in that this uses an italic font where a monospace font is needed instead. Also, as you can easily notice, it's the only entry in the table that doesn't use a template, but I cannot understand why such an exception was made. What do you think? Fturco 16:43, 9 October 2012 (UTC)

+1 by me. Some remarks about an implementation:

• The template shouldn't be named "Codeline" like in g-w.com, because this template should also cover other usecases like referencing parts of commands, etc. Also the name is to long for an often used template. Maybe "var".
• The styling should be distinguishable from other inline template, like {{Path}} and {{Key}}. This can also mean, that we change "Path".

We don't strive to be template-complete with g-w.com. We add templates, where we see need.

-Astaecker 11:03, 10 October 2012 (UTC)

If not adding a specific template like I proposed we can instead use <code>foo</code>, but definitely not ''foo''. The advantage of using a template is that, if the need arise, we can change the way inline code looks like by just editing the corresponding template in a single place; otherwise we have to look all over the wiki articles in search for inline code to alter. Anyway I can't find a proper, short name for this new template. Perhaps it's way too generic and we should stick with the <code> tag. Fturco 14:36, 10 October 2012 (UTC)

I'm in favor of a template. Just wanted it to be done right. What do you thing about renaming the "Code" template to "CodeBox" and using the "Code" name?

-Astaecker 16:03, 10 October 2012 (UTC)

Perhaps we can:

• Rename "Code" to "CodeBox", "File" to "FileBox", "Kernel" to "KernelBox"; these three templates are very similar, so I think it's better they all have the same suffix
• "Code" template name is not used now, so we can use it for generic inline code
• Rename "Path" template to "File"; directories, links, devices, etc. are all files in Linux, aren't they?
• "Kernel" template name is not used now, so we can use it for kernel options such as CONFIG_MODULES
• "Path" is not used now; it may be used if the need arises

At the end we would have Code/CodeBox, File/FileBox and Kernel/KernelBox. Yes, I like symmetric things :)

There would be a lot of work to fix things, but I'm ready to work on it. What do you think? Fturco 16:58, 10 October 2012 (UTC)

I like the Code/CodeBox and File/FileBox combos and renaming Kernel to KernelBox makes sense.

I don't like Kernel for CONFIG_* stuff. First, CONFIG_* stuff is not very user friendly (not descriptive, useless for make menuconf/*config ), and second, it has the same rationale as Code (highlight a snippet). So I would left Kernel unused.

So, I'm in favor, but we should get the others onboard. I thing, the change is too big for a "be bold and do it" approach.

-Astaecker 08:20, 11 October 2012 (UTC)

Cannot upload and link to ASCII/Text files

Seems only JPEG, PNG, ... image files can be uploaded and linked to within Wiki articles here. It would be nice to allow ASCII/Text files to be uploaded as well. --Roger 09:51, 17 October 2012 (UTC)

Bug #451074 (which I filed being unaware of this page) is related to this. --ulm (talk) 12:20, 19 January 2013 (UTC)

The "enabled per default" USE flag in the USEflag template

Talk status

	This discussion is done.

The {{USEflag}} template has a column named "default". I find it hard to say if a USE flag is enabled per default or not, the problem is you do not know which gentoo profile a document writer is using, or the document reader. We should define which gentoo profile is meant by "default" in this template. I have been assuming the "default gentoo profile" is meant here, which is very minimal, but a desktop will user assume the "desktop profile" is meant, which has already more USE flags enabled "per default". Which gentoo profile should we assume as mandatory for this template, so we have a baseline for further editing. I would suggest we should use the minimal "default gentoo profile" as a basis for this template, but I am open for other solutions. Needle (talk) 21:26, 6 May 2013 (UTC)

Good point. We should agree on a profile. I vote for a "default profile", based on assumed usage:

• For most articles, we should default on the "desktop" profile, because it's the most common used one (including "gnome" and "kde" subprofiles), I guess.
• For the articles in the Server & Security category, we should default on the "default" profile, again because it's the most common used one

Astaecker (talk) 08:37, 8 May 2013 (UTC)

That's fine with me, and easy enough for anyone else to follow. Needle (talk) 19:32, 13 May 2013 (UTC)