search

FDOS / freecom

FreeDOS Command Shell (command.com)
http://www.freedos.org/
GNU General Public License v2.0
158 stars 38 forks source link

html documentation #55

Open PerditionC opened 3 years ago

PerditionC commented 3 years ago

FreeCOM has detailed documentation about its supported features including internal commands.

This documentation is in a custom format and a perl script is ran to generate HTML from that.

It would be nice if someone experienced with perl could validate the script still works, fixup any issues such as current links to anchors don't actually link to anchors (instead of something like a href=#someanchor it used !!:someanchor) and document it - at least how to run it to properly generate all the html documents (though not sure if all the source files are there or not - extracted cmds.html from old release as it was missing).

Once the generation is known working, the actual source documents can be updated to match FreeCom's current feature set and timeline.

Question: should this documentation be in FreeCom's repository or would it be better to move the content to the htmlhelp program's COMMAND.COM documentation?

bttrx commented 2 years ago

Ah, you have also noticed documentation/scripts are somewhat broken. I'm no Perl expert, but I tinkered a while today and wish to share my observations.

  1. Running $ perl -I. ./db2html from the commands directory will generate files CMDLIST, TOC, and ../cmd.html.
  2. You need to run $ perl -I. ./db2html for a second time to include the TOC in ../cmd.html and have proper links. This is what the files CMDLIST and TOC are for, which don't exist on the first run. A near-chicken-egg problem.
  3. To have proper links in ../appendix.html and ../FreeCOM.html you also have to run perl -I. ./parseHTML. This will parse files commands/appendix.html and commands/FreeCOM.html.
bttrx commented 2 years ago

I noticed at least one 'command' is missing, which will give some defunct links. I created chgdrive.db:

name: CHGDRIVE
de: Change current drive
see: CD CDD DIR

SYNOPSIS:
EBNF: drive ':'

Make the specified drive the current drive.

EXAMPLE:

CMD: D:

Selects drive D: as the new current drive.

<P><EM>Note</EM>: If you key in <CMD>CHGDRIVE</CMD>, you will receive
&quot;Bad command or filename&quot;, because there is no real
<CMD>CHGDRIVE</CMD> command.
bttrx commented 2 years ago

Btw: For compatibility with SFN, I recommend to change .html files to .htm files. This should not hurt on LFN-aware systems.