search

ContentMine / norma

Convert XML/SVG/PDF into normalised, sectioned, scholarly HTML
Apache License 2.0
36 stars 21 forks source link

No man page or info doc #66

Open ghost opened 7 years ago

ghost commented 7 years ago

This issue report is based on using this JAR.

Norma follows the second convention described here, which is fair enough, but its output is excessive:

$ java -jar norma-0.5.0-SNAPSHOT-jar-with-dependencies.jar 2>&1 | wc -l
614

Users should not be expected to wade through 600+ lines of "help". Ideally, for usability, the help output should fit onto a single screen (~24 lines).

Additional information should be portioned off into one or more man pages or info files.

petermr commented 7 years ago

Closed as out of current scope

jkbcm commented 7 years ago

I think this could be something to address when delivering current projects. As a new user it slowed me down in getting started with the tools and gives a rather unwelcoming first impression which we would benefit from improving on. The issue with incorrect line-endings characters also affects this -- my shell prompt is left in the wrong place on Ubuntu (not returned the left), which is something we could fix as a quick win.

ghost commented 7 years ago

@petermr wrote:

Closed as out of current scope

This issue has not been assigned to a scope, so that is not a valid reason to close it.

In any case, I completely agree with @jkbcm that there is potential for quick, incremental, tidy-as-you-go improvements to be made within current projects, that would ameliorate - if not altogether resolve - issues like this.

ghost commented 7 years ago

When this issue comes to be addressed, it may be useful to consult the Gnits Standards for Command Line Interfaces, and possibly also the corresponding GNU standards.