I often find myself wanted to write-up documentation to read on a QL, user guides and the like, that could include some basic formatting, possibly tables or columns as well as linking to QL screen displays or sprites. And hyperlinks to other pages/bookmarks...
I've found a few potential candidates in Dilwyn's go-to repo, but not quite found what I'm looking for.
Before trying to design and code such a composer/reader and potentially re-invent the wheel, I thought to ask here first if anyone has already done the heavy lifting in such a project.
It should not require more than a bit of PE to allow it to be accessible to the broadest QL audience - the ProWess system for example is a bit overkill for what I'm looking for, as amazing as it is.
I thought I found something from Dilwyn himself at one point, but failed to bookmark it and then haven't been able to find it since
Could the PSION .hob file format be a starting point, or else Jochen's (I think) Help framework (sorry, can't recall it's proper title.)
Where I got to in the end was simple HTML. Almost any format: text, doc, pdf, bas, asm, etc, can be converted to HTML with relative ease. Perhaps we could find a standard set of tools to use for conversion. (For example M$ Word and Libre Office produce unnecessarily massive and convoluted files. There must be something better out there!) HTML viewers are available for almost any thinkable platform. If kept simple, one day, there could even be a useable browser for that kind of thing for the QL.
Simple HTML is also relatively easy to alter by hand where a bit of spit'n' polish is required. It might be nice to have a few standard CSS templates to work with so as to give a unified appearance to the documentation, where possible.
Per
I love long walks, especially when they are taken by people who annoy me.
- Fred Allen
Many ages ago, I looked into Markdown for the QL. I can't remember which variant ATM but I'll have a look see. If I remember correctly, it reads Markdown and writes Html, XML, Man pages, Commonmark source and LaTeX.
Thanks gentlemen - sounds like it's more than just a personal fancy after all and worthy of further attention.
Thanks Norm for that link to Markdown/CommonMark - if the C source can compile to a tight enough 68k binary, this might be a very effective starting point...
Some goals for the (fairly limited) set of requirements I see would be:
A: Able to render such a marked-up document on a base QL in mode 4/8, but also flexible enough to support high colours/linked graphics where available (possibly a set of images at various colour depths/resultions could be automatically selected depending upon the platform the reader/renderer was running on - and of course what has been composed and packaged with the document.)
B: Able to compose or convert ideally on a powerful enough QL/emulator, but otherwise on a host PC.
C: Support for some basic HTML-like markup formatting/structural options like the obvious bold/italic/underline (with suitable QL fonts loaded), as well as columns or simple tables and justification options for layout control and 'img' type tags to insert images.
D. Support for hyperlinking across a set of pages using 'a/href' type tags. Also, the ability in the reader/renderer to 'bookmark' pages or sub headings and maintain a list of visited sections to aid later navigation would be useful.
CSS and other more 'advanced' mark-up capabilities would be nice, but to meet item A. above, the simpler the better.
Whilst it would be very nice if the resultant marked-up doc met an existing standard for display in a modern HTML browser as well, I'd be comfortable if there was a 'Quill View' like PC-based application developed alongside to view the composed document outside the QL environment; sticking to 'proper' HTML, I suspect, might again make point A. above difficult to achieve.
I have also been looking for a mark-up text reader for the QL for some time. For my needs, a reader that supports a subset of Markdown would be sufficient (font types, image links, links to other documents, simple tables, ...).
To the requirements indicated by Martin, I would like to add another one:
E. That it also has an implementation as an extension (LRESPR) to be used within our SuperBasic programs.
(It’s a wish, maybe someday it will become a reality... )
I have also been looking for a mark-up text reader for the QL for some time. For my needs, a reader that supports a subset of Markdown would be sufficient (font types, image links, links to other documents, simple tables, ...).
To the requirements indicated by Martin, I would like to add another one:
E. That it also has an implementation as an extension (LRESPR) to be used within our SuperBasic programs.
(It’s a wish, maybe someday it will become a reality... )
I think what is important for a new reader format for the QL is:
Simple enough for a QL implementation. 1990's HTML would make sense or Markdown. More than some heading formats, bold, colored and maybe italics text plus hyperlinks wouldn't really be necessary. Graphics (pictures) support isn't really needed, I think (and already on the border of "too complicated"),
It should use a format that can be easily read and processed by modern PCs. I once fancied Quill _doc format for documents, but nowadays I find it very inconvenient not to be able to quickly view something on the PC or Mac.
Maybe RTF is what we're looking for. Can still be viewed on modern PCs, and is simple enough to be used on the QL.
An alternative would be heavily stripped-down HTML.
I think of it as two separate problems: 1) A collection of QL documentation
in an easily accessible format. 2) Being able to display that on a QL
platform.
The thing with HTML is that is can be simple and flexible and yet
beautifully displayed using standard tools available on most modern
computes. From a QL perspective, it is relatively easily parseable, and for
a QL client one could ignore anything that one cant cope with.
CSS is also easily parseable. One could use an agreed on subset, just
enough to enable one to make some individual adjustments in one personal
file rather than having to change all the documents. (For example for
people who are colour blind, etc)
HTML and CSS are rather fat and verbose; the tags take up a lot of room and
this slows things down. One could make a shortcut language which easily
translates back and forth from HTML/CSS, so that both markup systems could
be used. Ie the "original" documentation would be written in the standard
(early versions of) HTML/CSS and such documents could be "parsed down",
using a QL program, to produce a more compact script, with a reduced
property set, depending on the targeted QL platform it was to be viewed on.
It wouldnt matter if such a translator were slow or complex as it would
only have to be used once on each document, while the resulting output
could be viewed snappily on the QL platform.
I think hyperlinking is a must, as is bookmarking. Other than that bold,
underline, and italic are necessary. A choice of selected founts might not
be hard to implement. Colours where available. Images are needed to
illustrate certain concepts. Images would have to be pre-prepared according
to the targeted platform by the "down parser". Different character sizes
add a new layer of complication, and could be left out, at least to to
start with.
I have spent many hours experimenting with this kind of thing in the past,
but usually gave up when my nickers got in a twist at some point, or when I
got bored. To my mind it isnt hard to do, it just needs advance planning
once one knows what is wanted and what the capabilities of the target
platforms are. That being said, I dont wish to engage in making such a
product. I have other plans, things I need to finish before I move on to do
other things than programming. However, I wouldnt mind helping out where I
can.
I also experimented with RTF. The problem was that specs changed a lot -
at least at that time. It also was/is M$-specific and they could suddenly
decide to licence it, or do whatever.
Per
I love long walks, especially when they are taken by people who annoy me.
- Fred Allen
)
