Re: [gentoo-dev] markdown docs like README.md

[Kent Fredric]

On 25 September 2013 10:30, Tom Wijsman <TomWij@g.o> 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