Difference between pages "Welcome" and "Adding an Ebuild to the Wiki"

Revision as of 20:00, June 19, 2014

This page describes how to add an official entry for an ebuild to the Funtoo Linux wiki.

Goal

Our goal for ebuild wiki pages is ambitious -- the wiki should have complete and excellent documentation for using every ebuild in Portage. If the ebuild exists in your Funtoo Linux Portage tree, and there is no corresponding ebuild page for it, you're encouraged to use these instructions to add a page to the wiki for it.

What We Have So Far

To see what ebuild pages we have so far, see the Ebuilds by CatPkg page to see if the "CatPkg" (category/package atom) is already on this wiki.

You can also view all pages having to do with ebuilds (which also includes Package pages themselves) by going to the Category:Ebuilds page. Package pages will be listed by their regular wiki page names, which may make them harder to find.

The Package Namespace

This wiki has a special MediaWiki namespace called Package. Pages in this namespace have a URL that is prefixed with Package:, such as this wiki page: Package:Accelerated AMD Video Drivers, which is also a good example of a wiki page for an ebuild.

An Example Ebuild Page

Let's look at an ebuild page: Package:Accelerated AMD Video Drivers. You'll notice it has a unique look that is distinct from a regular wiki page.

There are several other notable things about package pages. Let's take a look at each:

As covered earlier, the ebuild is in the Package namespace.
The ebuild is in the Category:Ebuilds category.
In the left-hand Tools menu, you can click Browse Properties on an Ebuild page to view its queryable semantic properties.
There is an infobox in the upper-right corner that lists current ebuild maintainer, and the source repository to which it belongs, as well as its official CatPkg name.

One of the most important things to note about this Ebuild page is the name of the wiki page itself. Rather than being named x11-drivers/ati-drivers, as the ebuild is identified in the Portage tree, it has a regular English name as the wiki page name. Some ebuilds, like the Package:Nginx page, have the regular package name as the wiki page name. The general rule for naming ebuild pages is that they should be named as a regular wiki page, with a descriptive English name in the Package namespace. The Package namespace (as well as being part of the Category:Ebuilds category) indicates that this page is about a Package (ebuild.)

The rationale for this convention is to improve discoverability of these pages via search engines, and to align with wiki page conventions. The CatPkg is stored as semantic data so it is still possible to find the page using its traditional package atom.

Semantic Data

The following semantic data is stored for each Package page:

CatPkg (string) - the canonical name (catpkg atom) for the package in its overlay or repository.
Maintainer (Page) - a link to the maintainer(s) of this package (if the user has a User page, it will link there.)
Repository (Page) - a link to the repository from which this ebuild is sourced. This can be an overlay or a full Portage tree.
Summary (Text) - a short summary, typically a sentence, that describes the functionality of the ebuild.

Creating a Package Page

To add an Ebuild page to the wiki, use the widget below, which will pop up a form to guide you through the creation process. Remember the naming guidelines... If you were creating a wiki page for www-servers/apache, you would probably name the wiki page "Apache" or "Apache Web Server", and then enter www-servers/apache as the CatPkg on the form.

You will also be prompted for a Summary, Maintainer and a Repository. The Repository (as well as Maintainer) field will auto-complete, based on Users and Repositories defined on the wiki. If you don't know the right values for either of these, just leave them blank -- a staff member will fill them in properly for you. Our main goal is to get quality documentation online, so if you can help with that, fantastic!

Pages Need Approval

Anyone who signs up for a Funtoo account can create and edit wiki pages, but your additions/changes may need to be approved by a moderator before they are displayed. You can still edit and improve the page in the mean time. Once your edits have been approved, your changes will be on the official page that is displayed when anyone visits it.

Thanks very much for your contribution to Funtoo Linux documentation!

@@ Line 1: / Line 1: @@
-{{MainPageSidebar|1=
+This page describes how to add an official entry for an ebuild to the Funtoo Linux wiki.
-== Resources ==
-Our community has a number of excellent resources for communication and collaboration:
+== Goal ==
-* '''{{CreateAccount}}''' to log in to the wiki, forums and bug tracker. See [[Funtoo Authentication FAQ]].
+Our goal for ebuild wiki pages is ambitious -- the wiki should have complete and excellent documentation for using every ebuild in Portage. If the ebuild exists in your Funtoo Linux Portage tree, and there is no corresponding ebuild page for it, you're encouraged to use these instructions to add a page to the wiki for it.
-* '''[http://forums.funtoo.org forums.funtoo.org]''' - our new forums!
-* [https://groups.google.com/forum/#!forum/funtoo-dev funtoo-dev] mailing list
-* '''[http://bugs.funtoo.org bugs.funtoo.org]''', our bug tracker.
-* [http://larrythecow.org larrythecow.org], our Gentoo blog aggregation service.
-* [http://kernel-seeds.org kernel-seeds.org], resources for building your kernel from scratch.
-* [http://git.funtoo.org git.funtoo.org], our cgit repository browser.
-* '''[[Support Funtoo]]''' to help our project grow.
-* '''[[Funtoo Hosting|Get a Funtoo Virtual Container]]'''.
-}}
-{{MainPageSidebar|1=
-== UserMap ==
-{{#ask:[[Category:People]]
-|?Geoloc
-|format=googlemaps3|height=300|zoom=1|minzoom=1|markercluster=on}}
-[[Usermap|View Larger version]]
-}}
-== Welcome to Funtoo Linux ==
-Funtoo Linux is a Linux-based operating system that is a variant of [http://www.gentoo.org Gentoo Linux]. Funtoo Linux is:
-* ...'''fun!''' Our priority is to create a ''great, supportive and responsive'' user community.
-* ...'''user-centric and collaborative'''. Everyone is considered a '''user''' of Funtoo, first and foremost. You don't need any special privileges to collaborate with us.
-* ...'''production-oriented''': Our goal is to have Funtoo be useful for ''real-world tasks''. We use Funtoo to do stuff, like host our infrastructure. It needs to work.__NOTOC__
-* ...'''creative''': We seek creative, elegant and maintainable solutions to problems of all kinds.
-'''View the [[Funtoo Linux FAQ]] for answers to common questions.'''
+== What We Have So Far ==
-== Getting Started ==
+To see what ebuild pages we have so far, see the [[Ebuilds by CatPkg]] page to see if the "CatPkg" (category/package atom) is already on this wiki.
-We encourage you to [[Funtoo Linux Installation|install Funtoo Linux]], and get involved in our user community. Get to know fellow Funtoo Linux users on our [http://forums.funtoo.org forums]. If you have any improvements or find any bugs in Funtoo Linux, you are strongly encouraged to report them on our [http://bugs.funtoo.org bug tracker]. We take all bugs seriously, and all work performed on Funtoo Linux is tracked on our bug tracker, for purposes of transparency.
+You can also view all pages having to do with ebuilds (which also includes Package pages themselves) by going to the [[:Category:Ebuilds]] page. Package pages will be listed by their regular wiki page names, which may make them harder to find.
-Funtoo Linux has a very active [http://en.wikipedia.org/wiki/IRC IRC] community on Freenode, in the <code>#funtoo</code> channel, and you are encouraged to hang out online with us.
+== The Package Namespace ==
-== Project Structure ==
+This wiki has a special MediaWiki [http://www.mediawiki.org/wiki/Help:Namespaces namespace] called <code>Package</code>. Pages in this namespace have a URL that is prefixed with <code>Package:</code>, such as this wiki page: [[Package:Accelerated AMD Video Drivers]], which is also a good example of a wiki page for an ebuild.
-Funtoo Linux is led by [http://en.wikipedia.org/wiki/Daniel_Robbins_(computer_programmer) Daniel Robbins], the creator and former Chief Architect of [http://en.wikipedia.org/wiki/Gentoo_Linux Gentoo Linux], who serves as benevolent dictator for life (BDFL) of the project. Our organizational structure consists of BDFL and a small number of support staff, as well as members of our user community who are involved in improving Funtoo Linux. Development efforts are driven by the BDFL as well as our users, and efforts are under way to implement various mechanisms to allow supporters of Funtoo Linux to chart the future direction of the project.
+== An Example Ebuild Page ==
-'''Learn more about Funtoo Linux's development philosophy at [[Funtoo Linux Vision]].'''
+Let's look at an ebuild page: [[Package:Accelerated AMD Video Drivers]]. You'll notice it has a unique look that is distinct from a regular wiki page.
-== Distinctives ==
+There are several other notable things about package pages. Let's take a look at each:
-Funtoo Linux packages are installed from source code, automatically, thanks to the [http://en.wikipedia.org/wiki/Portage_(software) Portage ports system.], inspired by the FreeBSD ports system, but written in Python and with full advanced package management functionality. Funtoo Linux is a meta-distribution, which means it is built (fully automatically) with the functionality and optimizations that ''you'' want, not what some distro maintainer thought was best for you.
+* As covered earlier, the ebuild is in the Package namespace.
+* The ebuild is in the [[:Category:Ebuilds]] category.
+* In the left-hand Tools menu, you can click <code>Browse Properties</code> on an Ebuild page to view its queryable semantic properties.
+* There is an infobox in the upper-right corner that lists current ebuild maintainer, and the source repository to which it belongs, as well as its official CatPkg name.
-We use [http://en.wikipedia.org/wiki/Git_(software) Git] for all our development, and we also use Git to deliver our ports tree to you.
+'''One of the most important things to note about this Ebuild page is the name of the wiki page itself.''' Rather than being named <code>x11-drivers/ati-drivers</code>, as the ebuild is identified in the Portage tree, it has a regular English name as the wiki page name. Some ebuilds, like the [[Package:Nginx]] page, have the regular package name as the wiki page name. The general rule for naming ebuild pages is that they should be named as a regular wiki page, with a descriptive English name in the Package namespace. The Package namespace (as well as being part of the [[:Category:Ebuilds]] category) indicates that this page is about a Package (ebuild.)
-In contrast to Gentoo Linux, we offer a number of innovations, including our extensive use of git, [[Funtoo 1.0 Profile|our profile system]], [[Package:Boot-Update|boot-update]] boot management tool, our incredibly flexible [[Funtoo Linux Networking|template-based networking scripts]], [[Metro Quick Start Tutorial|Metro]] distribution build system, support of Debian, RHEL and other kernels, [[Creating_Python-related_Ebuilds|enhanced Python support]], Portage mini-manifests, user-centric distribution model, and a large number of community infrastructure improvements.
+The rationale for this convention is to improve discoverability of these pages via search engines, and to align with wiki page conventions. The CatPkg is stored as semantic data so it is still possible to find the page using its traditional package atom.
-== Help Document Ebuilds! ==
+== Semantic Data ==
-We need help adding documentation for ebuilds to our wiki. See below for a list of pages:
+The following semantic data is stored for each Package page:
-This page lists all ebuilds with pages on the Funtoo Linux wiki.
+* [[Property:CatPkg|CatPkg]] (string) - the canonical name (catpkg atom) for the package in its overlay or repository.
+* [[Property:Maintainer|Maintainer]] (Page) - a link to the maintainer(s) of this package (if the user has a User page, it will link there.)
+* [[Property:Repository|Repository]] (Page) - a link to the repository from which this ebuild is sourced. This can be an overlay or a full Portage tree.
+* [[Property:Summary|Summary]] (Text) - a short summary, typically a sentence, that describes the functionality of the ebuild.
-{{#ask:[[Category:Ebuilds]] [[CatPkg::+]]
+== Creating a Package Page ==
-|?CatPkg=
-|?Repository=
-|?Summary=
-|format=listwidget
-|link=all
-|headers=show
-|searchlabel=… further results
-|class=sortable wikitable smwtable
-}}
-'''Add an Ebuild page:''' (see [[Adding an Ebuild to the Wiki]] for instructions)
+To add an Ebuild page to the wiki, use the widget below, which will pop up a form to guide you through the creation process. Remember the naming guidelines... If you were creating a wiki page for <code>www-servers/apache</code>, you would probably name the wiki page "Apache" or "Apache Web Server", and ''then'' enter <code>www-servers/apache</code> as the ''CatPkg'' on the form.
+You will also be prompted for a Summary, Maintainer and a Repository. The Repository (as well as Maintainer) field will auto-complete, based on Users and Repositories defined on the wiki. If you don't know the right values for either of these, just leave them blank -- a staff member will fill them in properly for you. Our main goal is to get ''quality documentation'' online, so if you can help with that, fantastic!
 {{#forminput:form=Ebuild|size=|default value=|button text=Add Package|autocomplete on namespace=Package|remote autocompletion|placeholder=Descriptive name|query string=namespace=Package}}
-__NOTITLE__
+== Pages Need Approval ==
-__NOEDITSECTION__
+Anyone who signs up for a Funtoo account can create and edit wiki pages, but your additions/changes may need to be approved by a moderator before they are displayed. You can still edit and improve the page in the mean time. Once your edits have been approved, your changes will be on the official page that is displayed when anyone visits it.
+Thanks very much for your contribution to Funtoo Linux documentation!