Re: Pingus Readme

[Björn Fischer]

Neil Mitchell wrote:

> Hi,
>
> I was rooting around the SVN and noticed there are lots and lots of readme
> files, for different purposes, without particular clear meanings or up to
> date information. To combat this I think there needs to be one readme for
> users, and one for developers, and nothing else.
>
> I think the readme for users should also be in HTML format, instead of plain
> text. The reason for this is that a table of contents would be useful, and
> HTML does this a lot better. Also (minimal) styling would be nice, with
> proper topics. Also there are lots of links which would be clickable.
> Finally, all browsers support all line endings, however most text editors
> don't - so an HTML readme is if anything more viewable for more people.
>  

HTML is also better because then there won't be problem with CR/LF for 
line breaks on Windows. And at last every windows has the extention 
.html registered to a browser. With extensios like .unix or .languages 
this is usually not the case... It might be not that important, but 
nicer for win-users.

> I have written (or gathered together) such a readme for the users, and would
> like feedback - is this a better direction than lots of small readmes? Is
> HTML the right choice? Does the readme have the right content areas in? A
> lot of the topics need filling in, and in most cases thats because there is
> no equivalent information in other readmes around the place. 

I like the style and also the context areas seem sensitive to me. Maybe 
the "How to help" section can be a bit more detailed, but the rest is 
good I think.

The list is probably not complete, but the "How to help" section could 
express the following:

-    Take over the world (indeed a good point :-)
-    Send bug reports
-    Create new levels
-    Contribute to debugging and developing, if you are a programmer

> If this is the
> right direction, maybe checking it into SVN, and then anyone can submit
> patches (I have no idea about a lot of the stuff in there)
>
> This takes all the content from:
> AUTHORS
> COPYING
> INSTALL.unix
> README
> README.languages
>
> The files I have marked for inclusion in a developers readme are:
> INSTALL.unix
> INSTALL.Win32
> MAINTAINING
> README.Win32
>
> If this is a sensible idea, then I'll draft a basic developers readme as
> well and flesh out (or ask for information for) some of the topics in the
> user readme.
>  

This is a very sensible idea! I'm looking forward for the devel-readme :-)

Greetings

Björn