I found this email that Fritz sent to me off-list (it got lost in my
inbox) but I wanted to put this back on the freedos-devel email list
so we can discuss it here:
> The first question that has to be decided by Jim is if there are
> plans to support htmlhelp in the future. As reported several times
> it is buggy, crashes very often and the main problem is that it
> supports UTF-8, but only in about 250 UTF-8 characters when the
> correct codepage is activated. This was no problem till now with
> most European codepages. Turkish cp857 als works with htmlhelp, but
> when you write the help in UTF-8 it cannot translate the turkish "g"
> (gbreve) - and maybe some others. So turkish needs to be written with
> cp857 under all circumstances for htmlhelp. If you want I can try to
> make a small test version for you.
>
> AMB is nice, should support the turkish "g" (not tested) and has an
> option to import the primitive html files that we use (Mateusz does
> not love this option as he thinks that the internal .ama files are
> simpler). The reason why I prefer html is that I can simply upload the
> html files into internet and check if everything works fine, e.g. there
> is a tool to test if all internal links work fine. ama supports utf-8
> but does not have hyperlinks but simple and special types of links.
> And although you can write the text in UTF-8 (it makes cpxxx out of it)
> it is not able to export the UTF-8 to html. So my first question is:
> Will htmlhelp be given up or not?
>
I'll open this up to the FreeDOS developers.
I'm sort of in two states of mind on this. On one hand, HTML Help is
great. I like the idea that Help documentation can be maintained in
HTML files. That makes it really easy for folks to write
documentation.
I also like that HTML Help implements a simple version of HTML. It
doesn't understand <table>, <h4>, <h5>, or <h6> (these tags are
essentially ignored and displayed inline) but it can do other basic
documentation things like comments, <hr>, <h1>, <h2>, <h3>, <p>,
<pre>, <b>, <i>, and <a>. I didn't test other HTML tags, but at least
that subset seems to cover the essentials for writing technical
documentation. For example, I wrote this simple test file:
:: <html>
:: <head>
:: <title>Hi there!</title>
:: </head>
:: <body>
::
:: <h1>Hi there!</h1>
::
:: <p>This is a line of text.
:: This line has a few spaces at the beginning.
:: This is some sample text in
:: <b>bold</b>
:: <i>italics</i>
:: <!-- <u>underline</u> -->
:: .
::
::
:: This is a link: <a href="a.html">link</a>.
:: </p>
::
:: <h2>Heading 2</h2>
::
:: <h3>Heading 3</h3>
::
:: <!--
:: <h4>Heading 4</h4>
::
:: <h5>Heading 5</h5>
::
:: <h6>Heading 6</h6>
:: -->
::
:: <pre>
:: this is a preformatted block of text
:: this line has a few spaces at the start
:: and this line has <b>bold</b> and <i>italics</i>
:: </pre>
::
:: <!--
:: <table>
:: <tr><th>command</th><th>action</th></tr>
:: <tr><td>DIR</td><td>Display a directory</td></tr>
:: <tr><td>CHOICE</td><td>Display a prompt and wait for the user</td></tr>
:: </table>
:: -->
::
:: <p>This is the end</p>
::
:: </body>
:: </html>
..and that rendered correctly in HTML Help.
When AMB came up, with the accompanying AMB Help, I really liked it.
Such as a simple viewer implementation. Lightweight and fast. But on
the other hand, using AMBHELP requires converting the HTML Help files
to AMB format. And the extra step seems unnecessary. And I'm not sure
if AMB Help is significantly better than HTLP Help to justify the
extra step.
I don't know what bugs/issues remain in HTML Help (I didn't look it
up) but I think the "crash on language" issue was resolved.
I think I'm more in favor of keeping HTML Help as the standard Help
viewer. It's a faster turnaround for documentation (no file conversion
necessary) and makes it easier for new writers to contribute.
It would be nice if a maintainer could improve the program a bit.
While I don't think <h4>, <h5>, or <h6> is strictly necessary, it
would be nice to have them since that's the HTML spec. (They could
render as <i> and that would be fine for me.) And maybe update the
colors to use white-on-blue as the default .. or at least change the
blue borders to something that doesn't hurt my eyes (using /f2 looks
better, though). Otherwise, I think HTML Help is fine.
> The second question is: Which files / commands can be removed from help
> and which have to be added? E.g. backup / restore? Ralph Quint said
> that he wants to create the programs, but I am not sure if this will
> really happen. Others: scandisk, fdxms, fdxms286, mscdex, gcdrom etc?
> Examples for adding: fdimples, pgme etc.
>
If you're asking in preparation for "FreeDOS Next" (whether that's 1.4
or 2.0 is too early to say) I think we first need to decide what
commands we'll include.
> The third question is: Are there any proposals / ideas for modifying
> the look and feel of help? E.g. at htmlhelp there are buttons to go
> back within the book in the browser, at amb you have to press ESC (not
> explained everywhere) , at internet there is only the browser-built-in-
> "go back" option to go back. If you start anywhere in the middle via an
> Internet hyperlink you have no chance to find the rest. So I would add
> at least a go back hyperlink (amb-solution) at the bottom of each side.
>
Using Alt-C brings you back to the "table of contents." It's even
labeled that way at the bottom of the screen.
However, I think the bottom navigation hints in the HTML Help viewer
should change appearance (or maybe not appear) if there's no action
for that. For example, if I type:
HTMLHELP CHOICE
..to see the Help page for CHOICE, Alt-left (back .. same as Alt-B)
will just quit the program. Alt-F (forward) doesn't work, because
there is no "forward" to go to. I think it's confusing that hints are
displayed when they don't do anything. If I can't use Alt-F to go
forward, don't display it or show it in a different color ("bright"
version of menu background color?) so it is "iced" out.
Note that from the CHOICE Help page, if I hit Alt-C (contents) I will
get the "table of contents" page. And then I can use Alt-B or Alt-left
to go "back" to the CHOICE Help page, and from CHOICE use Alt-F to go
"forward" to the contents page.
> The fourth question: Would it make sense to add something like a "quick
> instruction for Newbies" inside? Most people including me are too lazy
> to read a whole manual. And I learned that the young generation never
> learned how to handle such a command line OS. They are mouse pusher as
> one of my trainer said years ago. So I would like to add something
> that explains the most important commands in a site that can be read
> within 5 or 10 minutes. Simply basics, like:
>[..]
> Sounds strange, but I learned from several trainings that the young
> guys never heard about it. And I think you do not want that these guys
> download the iso, install it and then are at C:\ and have no idea what
> to do and say: "What a bs..". But they read something about "help"
> before, type it and have no fun to read 290 help files.
Yes, I love the idea of a short tutorial article about how to use
FreeDOS, and making that part of the help. You can look through the
Books page and reuse or remix (or edit it whatever) as part of the
help.
Jim
_______________________________________________
Freedos-devel mailing list
Freedos-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/freedos-devel
