Issue2764

classification
Title: Readme is not displayed when using the GUI installer
Type: behaviour Severity: urgent
Components: Installer Versions:
Milestone: Jython 2.7.2
process
Status: pending Resolution: fixed
Dependencies: Superseder:
Assigned To: jeff.allen Nosy List: jamesmudd, jeff.allen, stefan.richthofer
Priority: high Keywords:

Created on 2019-04-27.22:16:31 by jamesmudd, last changed 2019-07-21.05:38:20 by jeff.allen.

Files
File name Uploaded Description Edit Remove
installer-missing-readme.png jamesmudd, 2019-04-27.22:17:49
Messages
msg12462 (view) Author: James Mudd (jamesmudd) Date: 2019-04-27.22:16:31
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?
msg12464 (view) Author: James Mudd (jamesmudd) Date: 2019-04-27.22:17:39
Previous discussion on this here https://github.com/jythontools/jython/pull/114
msg12466 (view) Author: James Mudd (jamesmudd) Date: 2019-04-28.10:59:15
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.
msg12470 (view) Author: Jeff Allen (jeff.allen) Date: 2019-04-28.17:20:08
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).
msg12472 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2019-04-28.20:26:54
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...
msg12474 (view) Author: Jeff Allen (jeff.allen) Date: 2019-04-29.06:53:18
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.
msg12476 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2019-04-29.20:15:09
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
msg12478 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2019-04-29.20:19:45
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.
msg12590 (view) Author: Jeff Allen (jeff.allen) Date: 2019-07-19.20:31:18
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.
msg12594 (view) Author: Jeff Allen (jeff.allen) Date: 2019-07-21.05:38:20
Fixed at: https://hg.python.org/jython/rev/5deb7d7984e8
History
Date User Action Args
2019-07-21 05:38:20jeff.allensetstatus: open -> pending
resolution: accepted -> fixed
messages: + msg12594
2019-07-19 20:31:18jeff.allensetassignee: jeff.allen
messages: + msg12590
2019-04-29 20:19:46stefan.richthofersetmessages: + msg12478
2019-04-29 20:15:09stefan.richthofersetmessages: + msg12476
2019-04-29 06:53:19jeff.allensetmessages: + msg12474
2019-04-28 20:26:54stefan.richthofersetnosy: + stefan.richthofer
messages: + msg12472
2019-04-28 17:20:08jeff.allensetresolution: accepted
messages: + msg12470
nosy: + jeff.allen
2019-04-28 10:59:15jamesmuddsetmessages: + msg12466
2019-04-27 22:17:49jamesmuddsetfiles: + installer-missing-readme.png
2019-04-27 22:17:39jamesmuddsetmessages: + msg12464
2019-04-27 22:16:31jamesmuddcreate