Re: [Mingw-cross-env-list] Do we still need a plain text README?

[Volker Grabsch]

Tony Theodore <address@hidden> schrieb:
> >
> > On the other hand, every plain text fan can browse the
> > doc/index.html with the favourite text browser, [...]
> 
> Trying to read html in a text editor is painful,

JFTR: I was talking about text browsers, not text editors.

To put it another way: "less" and "lynx" are just different
viewers. Is it really a big difference to type

    lynx index.html

instead of

    less README

?

> however, if people
> run into problems, they will most likely need a web browser of some
> sort anyway, so not generating a plain text copy of index.html won't
> really affect them.

That's another issue. However, I hope the included documentation
is helpful enough to make surfing in the web unnecessary.

> Thinking about a first time user though, the least surprising thing
> would be to have a plain text README in / rather than /doc.

Well, initially I really wanted to put README and ChangeLog into /,
but I feared that might clutter it. When you unpack the current
release, you'll find exactly three items:

    doc/
    src/
    Makefile

I think this is pretty self-explainatory even to novices. It is
clear that help is to be expected in the doc/ subdirectory, and
that running "make" might be a good idea.

However, entering doc/ things are no longer that clear:

    ChangeLog
    index.html
    README
    screenshot-4th-compile.png
    screenshot-4th-compile-small.png
    screenshot-4th-run.png
    screenshot-4th-run-small.png

It is not obvious where to start. Which is the "right"
documentation? README or index.html?

On the other hand, moving README (and ChangeLog) to /
might unclutter that subdirectory. Also, the README might
contain a pointer to doc/index.html instead of the text
browser dump.

So all in all, I see the following possibilities:

    A)  leave everything as it is

    B)  move README and ChangeLog from doc/ to /

    C)  same as B), but README contains only a pointer
        such as "see doc/index.html"

    D)  remove README, keep ChangeLog in doc/

    E)  remove README, move ChangeLog from doc/ to /

Any opinions on that? What do you think?


Greets,

    Volker

-- 
Volker Grabsch
---<<(())>>---
Administrator
NotJustHosting GbR