On 25 September 2013 10:30, Tom Wijsman <tom...@gentoo.org> wrote: > If I want to browse all documentation with a browser, just going to > something like file:///usr/share/doc and read them all in the same > style (using an extension like Stylebot or so); then it would be neat > if Gentoo could bring them down to the same format to me, instead of > that I would need to do local conversion or use multiple viewers for > what could be in one canonical place. >
How about doing it "Out of band" by a yet-to-exist gentoo tool that can create a format to the users liking on demand? I mean, whatever way you look at it, such a tool *MUST* exist to simply format the markdown to X-Format anyway. So why do this during ebuild phases? Why not have a tool that handles this? This greatly simplifies the problem that will transpire if we want to support more than one markdown standard, namely, an increased bulk of dependencies. As to identifying what standard to use for a given markdown document, I feel trying to do that automatically will result in sorrow, as will trying to develop one tool that handles all formats in the same document. I think maybe we could support a metafile of some description in the doc/<$pn-$pv>/ directory that describes a list of documents and the relevant format decoder to use for that document. This approach means we can do this for more than just markdown documents, and we can have support of extension-free files that happen to be in RST format instead, or ascii-doc, or whatever, ie: in /doc/$P/formats.meta README.md : markdown/gfm and then any of our tools can translate on demand to the format needed: less $PATH/README.md ^ could even be hooked to discover formats.meta and run the content through a ANSI formatter to translate bold indications into escape codes. And the same tool could be used as a backend for whatever web-browser centric documentation viewer we provide to render the files as html, or even do things like gentoo-fm $PATH/README.md --formatter pdf > /tmp/doc.pdf && okular /tmp/doc.pdf In the event somebody wants to read a simple markdown document as PDF. ( This also has the benefits of not necessarily adding a large amount of cruft to doc/ for people who don't need the documentation, and means they wont have to rebuild the package *JUST* to get documentation in a different format ) TL;DR - We can provide a tool, it doesn't have to be locked in to the ebuild phase to be useful, and could be more useful to be seperate of ebuild systems, with ebuild systems only providing minimal amounts of context to help a tool know how to process the document. -- Kent
