Gentoo Wiki:Suggestions/Archive

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

Stalled discussions and Archive
For discussions that haven't had contributions in a long time, see the Stalled discussions page, for completed discussion see the Archive subpage.

Print to PDF and/or Export to EBook File Format?
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)

Definition of Macros
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)

"desc" parameter for templates Code, File, Kernel
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)

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)
 * (which I filed being unaware of this page) is related to this. --ulm (talk) 12:20, 19 January 2013 (UTC)

A few suggestion
For Users
 * Display last modify date and last modify editor on each wiki page to let user know about the status of the docs.
 * Having Version tag, if the package need some different configuration we can have a version tag there to change the need but not the whole page. Even-thought gentoo are always updated it is still good to kept some history.
 * Kernel Template should have a format for kernel version -- it will be easier for other to understand and update.
 * Files Template should have some way to indication changes required. Current way is to paste the whole file and looking for changes are not good for users.

For Editor
 * New Page Template -- There should be a new page template which something like prerequisite, kernel requirement, emerge application files changes blah blah blah until the End to rc-update. This would be good for new and old editor as in future when there are some new things can be added in.
 * Kernel Template should be easier to use so should have a field like enable or disable and the kernel_module_name/the long name
 * Conflict in changes should have diff on top before the editor/content, this is easier to verify.

--dcmwai (talk) 05:10, 19 February 2014 (UTC)


 * ill second the need for version tagging configurations. samba 3 vs samba 4 are radical departures from each other.666threesixes666 (talk) 05:14, 19 February 2014 (UTC)

Questions about translating process
Some details of translating process not be clear for me. I made this discussion public, because answers can be helpful for other users, not only for me. Maybe this page not ideal place for such public questions, but I wasn't found any kind of 'common wiki discussions'.

About process organization, people who part in it and they permissions

 * Who (must || can) mark page for translating (add and )? Help:Translating page mention 'editors'. Is his authors of original page or category of wiki participants? If I guess what page ready for translating (I wasn't change original page, but want to translate page), then can I mark page for translating? If answer positive, how about 'Help' namespace, for example Help:Talk_pages?
 * Who (must || can) accept translating request? Help:Translating page mention 'administrator' and 'lead translator', but who is this people, is they active? How long typical time interval between request and accept/decline?

I believe, what open translating process is motivation itself for translators and working under understood process is more pleasantly, in contrast with closed or misunderstood process.


 * You can find who these people are through the special pages of the wiki (show users that are member of a particular group). Currently, I'm the lead translator in the sense that I'm marking documents for translation when these articles are (in my opinion) sufficiently well written and structured. Everyone who can edit a page can add in the  tags.

About translating tool and translating process himself

 * Can I translate several chunks of text simultaneously? Motivations of this is desire to keep uniform phrases forms and style of translated text, follow possibly mistakes — all its without write drafts. Lateral reason is more clear changes history.
 * How about translation teams pages (related to some target language)? Example stuff for such page can be found on my personal wiki page: links to dictionary (with indesirable examples!) and common recomendations for Russian Gentoo translators (from old rugentoo.org project). On such team pages experienced participants of corresponding translator team can share they experience with new translators.

Note that such translating team pages must be written on target language due to recomendations on this page related to target language.


 * Translation teams can work in parallel. Translations are done one paragraph at a time. --SwifT (talk) 19:15, 23 December 2014 (UTC)

--Totktonada (talk) 20:41, 21 March 2014 (UTC)

Template documentation
I just made [//wiki.gentoo.org/index.php?title=Template:Yes/doc&diff=160652&oldid=9167 this change] to the documentation of the Yes template because I thought having the bare text "unnamed" in the list of parameter names was potentially confusing. Then I realized a much larger discussion of template documentation is in order.

I'd like to implement a template-based approach to parameter documentation, so it can be standardized wiki-wide, and that requires some discussion of what format we want to use.

Here are some variations to consider...

This formatting currently seems to be the most common (taken from ContentBox/doc, but only showing the first 4 parameters): This is problematic for a couple of reasons. First, "1." is apparently being used to mean "first" and "2." to mean "second". Depending on the mix of parameters being documented, this can look like a numbered list (see File/doc), and it suggests (perhaps) that there are multiple parameters called "unnamed".
 * 1. unnamed: Add text or an image to the top-left heading box.
 * 2. unnamed: Add text to the main area.
 * color (optional): Border color of the box and background color of the top-left heading box.
 * bgcol (optional): Background color of the box.

Here's the example above rendered the way I did in my edit to Yes: But I'm not married to that format, by any means. I've seen the term "positional" used a lot for "unnamed" parameters, hence my use of the term above. Help:Templates calls them "anonymous", so maybe we should use that terminonlogy? BTW, the "[1]" and "[2]" are intended to allude to the fact that positional parameters can actually be referred to by number.
 * unnamed/positional [1]: Add text or an image to the top-left heading box.
 * unnamed/positional [2]: Add text to the main area.
 * color (optional): Border color of the box and background color of the top-left heading box.
 * bgcol (optional): Background color of the box.

Here's another possibility that makes the "positional parameters by number" idea more explicit: Here's the same thing marked up a bit more: (It might not be obvious that I've wrapped the parameter names in "code" tags and used 2 nonbreaking spaces to further separate the parenthetical text from the names.)
 * 1= (first unnamed/positional parameter) : Add text or an image to the top-left heading box.
 * 2= (second unnamed/positional parameter) : Add text to the main area.
 * color= (optional) : Border color of the box and background color of the top-left heading box.
 * bgcol= (optional) : Background color of the box.
 * (first unnamed/positional parameter) : Add text or an image to the top-left heading box.
 * (second unnamed/positional parameter) : Add text to the main area.
 * (optional) : Border color of the box and background color of the top-left heading box.
 * (optional) : Background color of the box.

Now, I've completely ignored the formatting of the descriptions, which are currently being rendered as if they were complete sentences, even though most of them are not. I'd actually prefer sentence fragments [phrases] with no ending punctuation. This, along with explicit indications of "required" parameters, gives my final example:
 * (first unnamed/positional parameter, required) : text or image to display in top-left heading box
 * (second unnamed/positional parameter, required) : main text
 * (optional) : border color of main box and background color of top-left heading box
 * (optional) : background color of main box

Whatever format we decide on, I'd like to use templates so that the last example, say, could be rendered by something like this:

(The "begin" and "end" templates enable further possibilities, such as using bullet-lists instead of definition-lists or wrapping the entire list in a "div" element.)

Opinions? - dcljr (talk) 05:44, 27 August 2014 (UTC)

Editing Handbook or protected wiki pages
Would someone add, if appropriate, a section here Help:Editing pages saying either how to edit protected pages or that it's not possible to edit them,  such as this one Handbook:AMD64/Working/Initscripts (there's currently a typo there which I would minor edit but can't: that "" part ) ? Thanks. --EmanueLczirai (talk) 19:28, 24 December 2014 (UTC)


 * Some locations, such as the  and   namespaces, are protected to only have developers and trusted contributors modify it. These namespaces contain resources that are more vital and thus warrant some additional ACLs. However, iirc, the discussion pages for those are still open so you can report fixes there. For the "" issue, I've corrected it. --SwifT (talk) 15:31, 27 December 2014 (UTC)


 * I'll use their discussion pages as suggested. Thank you! --EmanueLczirai (talk) 16:22, 27 December 2014 (UTC)

Request for a Command ( ) Tag Extension
When editing articles, I have been using the tags in paragraphs to help illustrate to readers when certian commands need to be run (see the GRUB2 article I modified today for the latest set of examples). I know a template exists, but since it is a template it is not useful for in-paragraph illustrations (since it creates line break). Would it be possible to create a tag extention so that writers can have a tag specifically for in-line command examples? For now I can continue using the ("something you type") sounds like a good tag for it, and it's even standard HTML: cat /etc/motd —a3li 11:26, 28 December 2014 (UTC)