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

[Tom Wijsman]

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

> Dnia 2013-09-25, o godz. 14:29:52
> Tom Wijsman <TomWij@g.o> napisał(a):
>
> > > > > 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.
> >
> > Neither is it a reason to stop progress.
>
> Excuse me but *how* is this related to progress at all?

Progress in providing choice, helping to support a single viewer.

> You're talking
> about converting *newer* format files to *older* format that will
> require special processing for display anyway.

The age or functionality of a format is not what we should discuss here
as it does not matter when talking about this progress.

> Worse than that, you are actually talking about doing the conversion
> *on files*, that is storing duplicate data.

Only if one chooses to do so, which hasn't even been decided yet.

> I'd expect progress to go *forward*. Introducing compatibility files
> for reading non-mandatory files using a web browser doesn't sound
> anywhere near progress.

That depends on how you define what is being progressed in; also if you
don't want to see compatibility, then yes, it is not progress for you.

> > > > > 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!
> >
> > Exactly, now this thread wants to make alternatives to that
> > possible; just because one tool exists doesn't mean everyone wants
> > to use it, there is no one size fits all solution. That's where
> > choice comes from.
>
> And what benefits do those 'alternatives' give us? Featurism, that's
> all. Implementing new features for the sake of doing something.
> Someone throws a random idea, let's implement it for the sake of
> choice.

Exactly, because an user came up with this; we're not implementing it
yet, we're still discussing it which doesn't mean that there is a team
of people that back certain decisions or implementation choices yet.

> Seriously, how many people actually *care* about
> reading /usr/share/doc with a HTML browser?

That's the question; we don't have statistics on this, maybe we could
make this a question in a future poll.

> How many people actually need it?

Those whom need it, it's not for us to judge what they should use.

> That is, how many people get real
> benefit rather than shiny formatting in their favorite tool.

That's exactly one of the reasons people want to use alternatives.

> Gentoo is not about bending everything upstream provides to match
> every tool a particular user likes.

Actually, it is; "Because of its near-unlimited adaptability, we call
Gentoo a meta-distribution." — http://www.gentoo.org/main/en/about.xml

> Improving the tools give more
> benefit than pushing compatibility cruft.

So, instead of storing it in a format the user appreciates we instead
patch it up in 20 browsers and make maintenance a lot harder?

Or the other option is to implement some kind of conversion HTTP web
server daemon from scratch; it's a lot more work to implement, but
that's the only still reasonable tool I could come up with. And it
doesn't necessarily have to do Markdown to HTML conversion alone; it
could possible be used to yield PDFs on the fly, have an interface you
can use to browse and search /usr/share/doc and so on...

Implementing such daemon wouldn't follow the KISS principle anymore.

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