RE: [External] : Re: Convert README.org to plain text README while installing package

[Drew Adams <drew.adams@oracle.com>]

All I meant there was that it's good if a
package description is written from a user point
of view - what it does for users, not just what
the author intended in writing the package.

The motivation and design underlying the package
are important, and _can_ be useful to document
(for users and others).  But most useful is what
you can do with it as a user.

> > Displaying a package description is for the
> > benefit of the user, not the author.  It's
> > about what's most useful for users.
> 
> Why do you think that a free software package author
> doesn't write his documentation for this very purpose?

I didn't presume anything about how or why every
pkg author writes their pkg doc.  I assume that
most do try to provide useful doc for users.

My point was only that the description should be
useful to users.  Whether the description "is
displayed as the author intended" is, on the
other hand, essentially a nice-to-have.  (And I,
as one user, really like to have it.)

And I was clear that authors should be able to
provide whatever display format/method they like.

But I think _also_ providing a plain-text
description of some sort (a plain README) should
be a minimal requirement - at least something
that's requested with "Please at least provide a
plain-text README."

> Exactly for this reason she has
> structured the README in sections, **emphasized
> the important parts**, included usage/config
> examples as highlighted

Absolutely nothing wrong with that - quite the
contrary.  That's to be hoped for, even expected.
No one said anything to the contrary.

> and added clickable links to [[helpful
> resources][https://...]].

No one said that authors shouldn't be able
to provide helpful links, images, and other
artifacts.  Even flashes and fireworks, if
they like.

> Why is it "most useful" for users to strip
> away parts of that?

No one said that that's the case.  Not I, at
least.  Are you looking for a straw man?

All I suggested was that authors should, at
a minimum, provide a simple, plain-text file
README.

I explicitly even said that (IMO) that file
need not say the same thing as whatever their
other, formatted README.* files say.

Why is a plain-text README desirable - useful
for everyone?  Because it requires minimal
paraphernalia to easily read it or otherwise
process it.  Lowest common denominator.  This
should be a no-brainer, I think.

> > Best is this, I think:
> >
> > 1. Require a plain-text README, as a minimum.
> > 2. Allow other formats, with appropriate file
> >    extensions (e.g. .md, .org).
> >
> > I see no reason for any limit on the kinds of
> > format, for #2.
> >
> > There should be, and likely are, simple ways
> > to generate a plain-text README from this or
> > that more structured format.  Condition #1
> > shouldn't be an obstacle to anyone, I'd think.
> 
> If there is some automatic conversion like for org,
> the obstacle is just that I as a package author
> would need to commit a generated file with the danger
> that contributors send patches against the generated
> document instead of the source.  Not a big deal but
> also not great.

As you say, neither a big deal, nor a great obstacle.
 
> > For Org, at least, that seems to confirm my
> > guess that such conversion's already available.
> 
> Yes, indeed.  I haven't seen anything like that for
> markdown (which is probably even more popular for
> READMEs than org), though.

Even producing a plain-text version by manual editing
is likely not a big deal in most cases.  That's my
guess, at least.