Jump to content
Read the Funtoo Newsletter: Summer 2023 ×

Join the Ebuild Documentation Effort!

Recommended Posts

  • Funtoo Linux BDFL

Hi All,

It's time to start getting Ebuild documentation in a modern format... so please help us add documentation for ebuilds to the wiki!
I have created a semantically-enabled directory of ebuilds on the Funtoo Linux wiki, which you can add to and expand. This is going to be the official set of documentation for all our ebuilds. Since we now have a wiki, we have tons more possibility for documenting ebuilds, so let's take advantage of it.
I have written up detailed docs on how to add an Ebuild to the wiki, documented here:
This effort is important to help everyone use ebuilds properly, and is also critical for the upcoming QA efforts, so it is an area of great need for the project right now.
Best Regards,
Link to comment
Share on other sites

  • 2 months later...
  • Funtoo Linux Developer

I noticed some ebuilds are documented as http://www.funtoo.org/PkgName instead of http://www.funtoo.org/Package:PkgName (eg. http://www.funtoo.org/Dbus). Some ebuilds are also linked from both schemes (eg. http://www.funtoo.org/Boot-Update and http://www.funtoo.org/Package:Boot-Update ).


I guess the prefered URL is http://www.funtoo.org/Package:PkgName. However, what should be done about old URLS? For instance, should I move http://www.funtoo.org/I3_Tiling_Window_Manager to http://www.funtoo.org/Package:I3_(Window_Manager) and add the {{Ebuild}} template? And how do I do a "symlink" from I3_Tiling_Window_Manager as with Boot-Update?



Link to comment
Share on other sites

I'm going out of a limb here, but reading through the wiki:


Our goal for ebuild wiki pages is ambitious -- the wiki should have complete and excellent documentation for using every ebuild in Portage. 


Could somebody maybe provide a bit more motivation for having such a goal?


On first glance it seems like the request for a lot of duplicated effort. The Gentoo wiki has a lot of documentation and the Arch Linux Wiki is probably one of the best resources for packages of all kind, not to mention the man page (although it is true that some man pages completely lack any depth).


Why am I asking this?

Let's take an recent page that was added to the wiki:


Although max kudos to the person who wrote this, isn't all of the information present on that page already available elsewhere?


I completely agree that writing documentation / help is possibly the most important (non code related) contributions to be made to opensource but is such a massive duplication of work necessary? Shouldn't the Funtoo wiki restrict itself to Funtoo-specific changes in the packages?


Now I might be horribly wrong here and I apologize for making ignorant claims, but shouldn't there be some clear "Why do we want to do this / Motivation" section in addition to the "Goal" one in http://www.funtoo.org/Adding_an_Ebuild_to_the_Wiki ?


Link to comment
Share on other sites

right, were a documentation driven distribution as is arch, gentoo, and linux from scratch...  look at our mediawiki ebuild, i doubt you'll find such an excellent mediawiki cheat sheet anywhere....  why document more than what you have insane tweeks of?  to let people know where to get general info, and all the tweeks they need to know.  i started documenting @ gentoo to address forum posts so i could have a manual to point at when a recurring problem came up, i could repeatedly answer with a link.  instead of 50 thousand threads with hurricanes of chatter going on, you get a concise document, that is incrementally improved.  think of it like forums, but cheat codes of the universe instead of chatter, and filler text.  forums, think of as having to read 30 posts that are not helpful to find 20 useful posts.




https://wiki.archlinux.org/index.php/Mediawiki <--- junky

http://wiki.gentoo.org/wiki/Mediawiki <---- really junky


http://www.funtoo.org/Package:MediaWiki#Tips_and_Tricks <---- excellent cheat codes


im working on building this:



so that our page can be stack choices agnostic, i can serve mediawiki via lighttpd, nginx + phpfpm, or apache.  right now i only know mysql, but im sure eventually postgresql, mariadb, percona, or what ever else database will be a well documented choice also.

Link to comment
Share on other sites

  • 1 month later...
  • Funtoo Linux BDFL

No, don't worry about USE except when it comes up for tips/tricks related to successful install. I am automatically importing USE flag descriptions from metadata.xml for forked and overlay ebuilds and hope to add Gentoo ones soon.

Link to comment
Share on other sites

  • Create New...