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

[Tom Wijsman]

On Wed, 25 Sep 2013 11:27:50 +1200
Kent Fredric <kentfredric@×××××.com> wrote:

> 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.

That sounds like a converter.

> So why do this during ebuild phases? Why not have a tool that handles
> this?

Because we are discussing conversion in an ebuild context.

> This greatly simplifies the problem that will transpire if we want to
> support more than one markdown standard, namely, an increased bulk of
> dependencies.

The existence of a tool does not exclude that an ebuild cannot use it;
so, I agree with your paragraph but that doesn't necessarily mean we can
apply this in an ebuild context.

> 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.

Yes, automatic detection and applying a whole conversion based on that
detection would be bad; writing something that only deals with the
common elements, would be more neat. 

The question being whether we want to focus on the original Markdown or
the GitHub Flavored Markdown to base ourselves on.

> 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.

Why does documentation generation and/or conversion so suddenly be done
by the user? it needlessly complicates things, especially since the
user now has to store those generated or converted in a separate
location; this is not the way it has been done and I don't understand
why we need any change in that.

The maintainer could specify the format in the ebuild; for bugs where
it has found to be of a different format, this is an easy fix.

> 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:

This is no longer a discussion with regard to Markdown; but a whole
topic on its own, at least if you want to be pursue consistency it
might be worth bringing this up its own thread (or at least change the
subject to denote it is no longer about Markdown in specific).

> and then any of our tools can translate on demand to the format
> needed:
>
> ^ could even be hooked to discover formats.meta and run the content
> through a ANSI formatter to translate bold indications into escape
> codes.

My browser can't; so, I'll need conversion.
 
> 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

What kind of backend would this be? A web server daemon?

> 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.

But why should we go through hard hoops to read something simple?

Why not just have it installed and opened in the format the user wants?

> ( 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 )

That doesn't happen as these are controlled with USE flags; eg, USE=pdf.

If we plan on introducing more documentation formats, we might want to
introduce an USE expand to make it easier for the user to configure;
instead of the local USE flags we are using now.

> TL;DR - We can provide a tool, it doesn't have to be locked in to the
> ebuild phase to be useful,

Tools used by ebuilds and eclasses can usually be used outside that
context as well; it isn't really locked, and its usefulness doesn't
change depending on where it is used. It's rather what the addition of
the context you place it in that matters here.

> and could be more useful to be seperate of ebuild systems,

Perhaps it could be, but I don't see why; it feels less handy to do.

> with ebuild systems only providing minimal amounts of
> context to help a tool know how to process the document.

If you put the tool in the context of the user, maintainers will not
really be aware of or contributing to the context; eg. formats.meta.
This would put the format responsibility in the hands of the user...

Whereas if it was in an ebuild, it could be a matter of changing `domd
README.md` to `domd -gfm README.md` (or if gfm defaults, to `domd -orig
README.md`). No separate file, barely any extra characters; easy to fix.

And as a result, documentation files in the format that the user wants.

"Here, format X you don't like." --> "Which format would you like?"

-- 
With kind regards,

Tom Wijsman (TomWij)
Gentoo Developer

E-mail address  : TomWij@g.o
GPG Public Key  : 6D34E57D
GPG Fingerprint : C165 AF18 AB4C 400B C3D2  ABF0 95B2 1FCD 6D34 E57D