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

[Tom Wijsman]

On Wed, 25 Sep 2013 00:07:15 +0200
Michał Górny <mgorny@g.o> wrote:

> Dnia 2013-09-24, o godz. 23:50:20
> Tom Wijsman <TomWij@g.o> napisał(a):
>
> > Principle or not, we shouldn't force our users down a particular
> > way to reading them; as that's not what our meta-distribution
> > stands for.
>
> We shouldn't either work on working for every fancy a single user may
> have. If there's a real benefit from converting markdown to HTML,
> please show me one.

It brings them to the same structure as any other HTML documentation;
if I'm going to take a complete opposite idea, we could also consider
converting PDFs to HTML for people whom don't want a PDF reader or
want to read the documentation on another device that doesn't even
support PDF. Furthermore, HTML and CSS gives them control on how the
text should be formatting; something both PDF and Markdown does not.

PDF is of course not the best example, because the binary of a PDF isn't
really readable to a human whereas Markdown was meant to stay readable;
but I'm just saying that whereas you might not see a benefit, that
doesn't mean that nobody else does.

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.

Why do I need a browser, a PDF reader and a Markdown viewer and
possibly more clients to read my documentation in a formatted way?

> As far as I can see it, we're either talking about:
>
> 1) replacing semi-readable Markdown with unreadable HTML that will
> require special tools for proper display,

Just some basic CSS will do just fine.

> 2) installing duplicate files (the same data in markdown and in HTML),

This hasn't been discussed yet; but it doesn't need to, it's the usual
INSTALL_MASK story.

> 3) adding some more ugly awful magic that will make binary packages
> even less useful.

For binary packages a choice has to be made; trying to solve things for
binary packages is like discussing something to be implemented on a
binary distro, you simply can't bring the usefulness we are discussing
here to a binary package because of its nature.

> That said, I'd rather see people using *tools* to display Markdown
> rather than converting everything 90s-style.

I'd rather have a single tool that displays documentation and display
it really well; people are still converting things these days, they
will continue to do so in the future. Some things aren't compatible.

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