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

[Michał Górny]

Dnia 2013-09-25, o godz. 00:30:27
Tom Wijsman <TomWij@g.o> napisał(a):

> On Wed, 25 Sep 2013 00:07:15 +0200
> Michał Górny <mgorny@g.o> wrote:
>
> 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?

And why do I need a special HTML-formatting tool (which is much more
expensive) to read documentation in any way? Or rather, to drop all
the useless formatting.

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

And how does that help with 'cat' output? Or vim? Or many other
standard *console* tools Gentoo users use.

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

And how does this distinguish between HTML cruft converted from
Markdown and HTML-only docs?

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

Which is not reason to make it even worse.

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

It's called 'less'. Open a bug against it, ask our devs to include
a formatter in 'lesspipe'. Tadaam!

-- 
Best regards,
Michał Górny