Subj : New documentation
To   : All
From : Sean Dennis
Date : Fri Apr 15 2022 06:09 pm

Hello All,

To say that MBSE's documentation is very outdated and in shambles is an
understatement so I have been quietly working on new documentation for MBSE
from HTML to PDF using LaTeX.  It's not easy considering my health these days
and the use of a 28-year-old Model M keyboard that is shorting out and causing
random letters to appear from time to time but I am determined to get this
going

So what I do is I convert the HTML to LaTeX with pandoc and use TeXstudio and
Geany (to work with tables) to create the master document in TeX.  I then call
pdflatex to create the PDF.

What is very nice is that the resulting PDF:

 - Has a table of contents with hyperlinks within the PDF
 - Has a very nice index for quick reference
 - Is printable
 - Is easily searchable

It is also much easier to update a TeX document than HTML.

I am right now just in the process of converting the HTML to TeX.  I still
have a *LOT* of work to do just in that scope.

After I get the HTML converted, then I have to:

 - Fix Michiel's bad English <G>
 - Rework many sections to be much easier to understand
 - Add in important yet missing information (lots of that)
 - Rewrite the DOS doors section for today's setup with DOSemu
 - Add in a Linux-native doors section
 - Add in all of the improvements that have been made
 - Create new screenshots (need to get rid of that one screenshot that
discusses all the porn areas in Dreamland BBS)
 - ...and much much more.

I have moved the global menu options and the ANSI/ASCII screen control codes
to their own appendicies which will make quick searching much, much easier.  I
have also moved all of the open source licenses to their own appendicies.

I want to add in a LOT of more information, such as how to fully set up DOS
doors, how to set up file hatching, update the httpd and ftpd setup
documentation (it is badly out of date), Vince's log rotation script, et
cetera.

It is a very slow, deliberate process that will take me months right now.  If
I get my Social Security and can afford to create a more comfortable
"operating position" with a modern Model M[1] keyboard and two larger
monitors, that will make things go much, much faster.

If anyone is interested in the current PDF, let me know privately and I will
make it available to you.  It's still a huge mess.  What is really killing me
is that Michiel did not use HTML tables in the current documentation and
creating tables in TeX/LaTeX is time-consuming.

But so far, so good.  LaTeX does a wonderful job with formatting and making
the new documentation look so much nicer.

Once I get this project to a stable condition (I will never say "done"), I
want to convert the LaTeX to Markdown and put the entire documentation into
the project's wiki on the Sourceforge site.

After that, I want to work on making MBSE create HTML 5-compatible webpages
and make the look of the webpages somewhat customizable through the use of a
configuration file.  The pages MBSE creates will still be static but they will
be modern and can take advantage of the modern features of HTML 5.

An example of what I am talking about is my own BBS website at
http(s)://outpostbbs.net -- I use HTML 5 and CSS Level 3 + SVG to create the
dropdown menu and handle the page layout.  For those worried about text-based
browsers such as links and Lynx,  the site still works though it's not quite
as "pretty".  I test my websites using links2 in text and graphics modes and
Lynx.

Sorry for the long post but there's a lot going on for me. <G>

-- Sean

... Documentation: the worst part of programming!
--- GoldED+/LNX 1.1.5-b20180707
* Origin: Outpost BBS (MBSE BBS Dev Team) (1:18/200)

You are viewing proxied material from vert.synchro.net. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.