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

[Tom Wijsman]

On Wed, 25 Sep 2013 09:57:26 +0200
Michał Górny <mgorny@g.o> wrote:

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

Who says you need to?

We're not suggesting completely replacing what we currently have as far
as I am aware of; so, if you don't want to see a change in what is
installed for you, you'll be able to keep it that way under what is
being suggested in this thread. Choice implies that you can keep things
the way they have been.

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

You just choose to not use a converter. No problem here.

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

Looking at the mailing list history, I could use this binary package
argument on many threads. People that want binary packages should live
with a default under the current implementation; as for a possible
future implementation, that could possibly have split up tarballs so we
can selectively install parts of the binary package such that this would
not be a problem at all. Discussing binary packages here is off-topic.

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

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