Issue2764

The readme is not displayed when using the GUI installer see screenshot attached.

When using the command line install it is also missing e.g

pi@raspberrypi:~/git/jython/dist $ java -jar jython-installer.jar 
    Welcome to Jython !
    You are about to install Jython version 2.7.2a1+
    (at any time, answer c to cancel the installation)
    For the installation process, the following languages are available: English, German
    Please select your language [E/g] >>> 
    Do you want to read the license agreement now ? [y/N] >>> 
    Do you accept the license agreement ? [Y/n] >>> 
    The following installation types are available:
      1. All (everything, including sources)
      2. Standard (core, library modules, demos and examples, documentation)
      3. Minimum (core)
      9. Standalone (a single, executable .jar)
    Please select the installation type [ 1 /2/3/9] >>> 
    Do you want to exclude parts from the installation ? [y/N] >>> 
    Please enter the target directory >>> /home/pi/jython
    Unable to find directory /home/pi/jython, create it ? [Y/n] >>> 
    Your java version to start Jython is: Oracle Corporation / 1.8.0_65
    Your operating system version is: Linux / 4.14.98-v7+
    Summary:
      - mod: true
      - demo: true
      - doc: true
      - src: true
      - ensurepip: true
      - JRE: /usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt/jre
    Please confirm copying of files to directory /home/pi/jython [Y/n] >>> 
     10 %
     20 %
     30 %
     40 %
     50 %
     60 %
     70 %
     80 %
    Generating start scripts ...
    Installing pip and setuptools
     90 %
    Collecting setuptools
    Collecting pip
    Installing collected packages: setuptools, pip
    Successfully installed pip-9.0.1 setuptools-28.8.0
     100 %
    Do you want to show the contents of README ? [y/N] >>> y
    null
    Please press Enter to proceed >>> 
    Congratulations! You successfully installed Jython 2.7.2a1+ to directory /home/pi/jython.

The readme is null. I suspect this occurred when i changed the readme to markdown. Should we also maintain the txt readme for this reason?

Previous discussion on this here https://github.com/jythontools/jython/pull/114

Just considering this issue, i'm wondering if we should replace the readme with a link to the website? It would be good in that its up to date,i.e. if you run an old installer it would link you to the readme where you would see there is a new version, but equally that would be an issue that the readme would no longer be linked to the version you are installing.

Of course the simplest fix here is to restore the text readme but wonder if there is a better solution.

All this assume anyone reads it anyway lol.

I think it should definitely show you a README delivered with the version being installed.

There were template variables in an old version of the README.txt that I didn't understand and there is a reference in build.xml. Evidently, by working as a team, we can break almost anything ;)

Done right, it would fix the consistent version problem. If processing involves a script somewhere, maybe it could strip the markdown to something readable. It would be good if it worked across platforms and with Gradle (for the future).

What about changing it to rst? Github also supports rst rendering and rst reads much nicer in raw form, close to a pretty formatted txt file. Given that there is hardly fancy formatted content in the readme it shouldn't be too much work to change it to rst.
Somehow it must be possible to tell the installer the new readme is README.rst rather than .txt...

Both types seem readable as text as long as one is not too adventurous. (https://daringfireball.net/projects/markdown/syntax#philosophy)

The installer is quite complex (and customisable). It could probably be made to reproduce just a "readable" portion of the readme (.md or .rst), where everything "adventurous" lies outside it. But I quite like just going with the plain .md and no fancy stuff.

Okay, then let's however switch to underline-style headers rather than ###. I find this the main factor causing ugly look. (Just thought it would be rst vs md, but if md supports underline headers that's fine)

This is an H1
=============

This is an H2
-------------

vs

#This is an H1

##This is an H2

The code for the logo and badges is still a bit ugly. However I find it less of an issue than messing around with two redundant readme files. I don't think it's worth the effort to configure the installer to do text processing on the readme (if it's possible at all). At maximum, it could simply skip the first two or three lines which contain the badges. But only if that's somewhat straight forward. I'll see if I can have a look how this works.

I think we need both README.txt and README.md. It is a pain to keep them in sync, but I don't think we need to.

README.md (on the master branch, anyway) changes as the project evolves, not in sync with a release. I always think "how to build this project" is the most valuable information. (On other branches it can do it for that branch or a label.)

README.txt contains what we want to say at installation time, to someone who may be using Jython for the first time. This would not include "how to build this project". It could include prominent acknowledgements or warnings. README.txt should probably confirm the version, although the installer does that anyway.

Fortunately, James had the perspicuity to make removing README.txt a separate change set, so I'll revert that and adjust the content.

Fixed at: https://hg.python.org/jython/rev/5deb7d7984e8