1. Forum
  2. FIDO
  3. MBSE

  • New documentation

    From Sean Dennis@1:18/200 to All on Fri Apr 15 18:09:16 2022
    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)
  • From Vincent Coen@2:250/1 to Sean Dennis on Sat Apr 16 14:13:20 2022
    Hello Sean!

    Answering a msg of <Friday April 15 2022>, from you to All:


    Did you take a look at mbse-1.odt ?
    It is in the docs directory of the sources along with the mbse-1.pdf file.
    It was created using LibreOffice but can be read from MS Word I understand. (LibreOffice is a O/S product that is free to get and use and works in a similar way to MS Office and Word).


    As I did the convert process a few years back with only light changes, speeling
    errors and other sillies fixed up.

    I also started with one or more tables at least for the FAQ's but run out of time so left the rest 'as is'.

    The other issue is that as manual the entire document needs a rehash as it is impossible to use when setting up a mbse system for the first time.

    At the moment I am setting up a new system on a Pi to process the elist software as an independent system and that box will only make use of :

    Echos : ELIST, ECHOLIST and Netmail in the name of elistmaint (at 2:25/21)

    Files:
    ECHOLIST (the elist monthly archive)
    Z2DAILY for a up to date copy of the nodelist and yes it could be Z1DAILY
    but the Z2 one is more up to date on a daily basis.

    Possibly NODELISZ but made inactive anyway as the DAILY does the same job and is updated daily.

    Mbse using AKA 2:25/21 with its uplink as 2:250/1 (or possibly 1:3634/12 but made inactive) - I need to speak to Mark Lewis on this if needed as live).
    As it is 250/1 is a master Hub for Filegate and passes on echo's and files to/from all Mark and/or the other FileGate Star Hub systems.


    The idea is that a small box will hold the elist system along with the source programs that make up the elist (and backbone) system so in the event when I get ill or die etc some one younger can take this role overbut just paying for P&P and a contribution to wards to cost of the Pi (and HDD and metal casing
    and (laptop type Power adaptor).

    All that would be required to get it operation is :
    1. If not acting as headless - wireless keyboard and mouse (Logitech Kbd - K360
    and mouse - M325):
    2. Twin power lead with a sideways 8 connector for country of operation.
    3. HDMI cable to connect to a monitor device which as as input HDMI.
    4. Lan cable to conenct to router or a hub/switch.
    The Pi can use Wireless connection for networking but cable likely to be
    faster.
    5. Change to Pi to support router network as currently set to 192.168.1.254 for
    router and internal address as 192.168.1.75
    6. Arrange for new Net address is required but can use initially 2:25/21 with
    a change of IBN url.
    7. Change mbse to use that address.
    8. Change mbse to use another uplink address.

    That it.



    Vincent

    --- Mageia Linux v8 X64/Mbse v1.0.8/GoldED+/LNX 1.1.5-b20180707
    * Origin: Air Applewood, The Linux Gateway to the UK & Eire (2:250/1)
  • From Sean Dennis@1:18/200 to Vincent Coen on Sat Apr 16 11:58:00 2022
    Hello Vincent,

    16 Apr 22 14:13, you wrote to me:

    The idea is that a small box will hold the elist system along with the source programs that make up the elist (and backbone) system so in the event when I get ill or die etc some one younger can take this role overbut just paying for P&P and a contribution to wards to cost of the
    Pi (and HDD and metal casing and (laptop type Power adaptor).

    It's a good idea. Nice to have a business continuity plan, if you will.

    Something I want to say publicly: my documentation project is not to dimishish all of the work you did on the MBSE documentation. I am just rewriting it using LaTeX so that way anyone who has to work on it in the future will be able to have an easier time than dealing with HTML. I was willing to learn LaTeX/TeX to do this not only for this projecct, but for my own Cheepware doors which I have released as open source.

    Let me tell you, I stepped into a deep puddle with this project. <G> It's a LOT more more than I expected but I am wanting to do this because, like you said, the current MBSE documentation is damn near worthless right now from its age and unreadability.

    -- Sean

    ... Forty isn't considered old if you're a tree.
    --- GoldED+/LNX 1.1.5-b20180707
    * Origin: Outpost BBS (MBSE BBS Dev Team) (1:18/200)
  • From Vincent Coen@2:250/1 to Sean Dennis on Sun Apr 17 03:20:25 2022
    Hello Sean!

    Saturday April 16 2022 11:58, you wrote to me:

    Hello Vincent,


    Let me tell you, I stepped into a deep puddle with this project. <G>
    It's a LOT more more than I expected but I am wanting to do this
    because, like you said, the current MBSE documentation is damn near worthless right now from its age and unreadability.

    I have to use texlive with gnucobol project as that is what the manual was written and I do not like it one bit.

    So good luck with it, I will not be doing any changes to a texi based manual. One is more than enough.

    Did not lick playing with html as well so I converted it into LibreOffice OFT and could with a click of a mouse do the same for .doc or .docx - I just do not
    have word on my Linux system but LibreOffice work on all platforms and I
    prefer using a WYSIWYG processor.

    Vincent

    --- Mageia Linux v8 X64/Mbse v1.0.8/GoldED+/LNX 1.1.5-b20180707
    * Origin: Air Applewood, The Linux Gateway to the UK & Eire (2:250/1)