Hallo Besucher, der Thread wurde 36k mal aufgerufen und enthält 124 Antworten

letzter Beitrag von adtbm am

BASIC 10 chapter of the MEGA65 manual finished today

    Hi everybody,


    today, one of our great violunteers in the MEGA65 team, finished quite a trip (or how he states, a snake-pit ;-) ) and finished the whole BASIC 10 chapter for the MEGA65 manual.

    So i would like to take the opportunity and thank Edilbert here personally !!! THANKS Edilbert !!! Great job !!! It looks amazing !!! :thnks:


    i take the freedom and copy Paul's Blog entry over here, so have fun reading it. The manual and everything else we develop will be made available

    and everybody who buys a MEGA65 will have the manual included...80's style :-D

    You can read the Blog also directly on Paul's site.

    So without anymore talk, here you go:


    BASIC 10 Reference

    Today we have a guest post from Edilbert, one of our great volunteers in the MEGA65 team, who has been working on documentation for BASIC 10. As you will discover, this was no small task. But I'll stop here, and hand over to Edilbert...


    I followed the MEGA-65 for some years and wondered how long it would take
    until I could buy this fascinating machine. Then I read Paul's post in the
    Forum64, where he asked for support. So I thought, it would be nice to join
    the team and contribute.


    Initially I thought, I could do some assembly
    programming for the operating system or the BASIC interprenter, but they
    needed writers for the user's guide. So I proposed to write the chapter:
    BASIC-10 command summary. I really underestimated the work, that would be
    needed.

    First, I had to write the stuff new with my own words - no copy and paste
    from existing sources. Preliminary versions of the Commodore C65 exist,
    but they cannot be used for copyright reasons.


    Then I got access to the repository with the stuff, that was created already.
    It was a bunch of LaTeX files with some text, some program generated
    tables and templates for all planned chapters. Well, I thought to
    be an expert in LaTeX, because I wrote all my scientific papers with that
    program, but then I always got layout templates from the journal editors
    and had to insert text, figures and citations.

    This one was a completely different beast. It was a snake pit.
    First I had to install some extra packages, that were unknown to me.
    After the first successfull LaTeX run I got a pdf (hurrah) but also a log
    file with more than 6000 lines of errors and warnings.
    I thinks, this was due to the effect, that different contributors used
    packages, that were sometimes incompatible.
    So I decided, that I should first read through the log file and eliminate
    as much errors and warnings as I could. This was not easy, but I managed to
    find solutions and workarounds in most cases.


    The next problem was the screen font, that was used to illustrate example
    programs. The used font was for 40 column screens and not free of copyrights.
    So I created my own true type font for this purpose for a 40 column
    and a 80 column screen.


    Now I started to fill in the contents for the BASIC-10 chapter.
    I took the syntax from existing sources but wrote a new text for the
    description and tried to find a compromise between mathematical correct
    and user friendly formulation, which is sometimes difficult.

    I wrote 190 pages of text, thought about example code, tested this code on
    a Commodore 128, where possible and tried to make it readable.


    The result is a page like this for every BASIC 10 keyword, with the nice screen font for showing how examples would be typed:



    Bildschirmfoto%2B2019-10-20%2Bum%2B17.57.21.png


    The LaTeX source for a page like this would be:


    Bildschirmfoto%2B2019-10-20%2Bum%2B17.58.28.png



    Now after 6 months and more than 150 work hours the chapter is written.

    We need probably some revision, to improve the English, make some text
    clearer and insert better code snippets, but the first version is done.


    Now I'll focus on the screen font (add graphic symbols) and layout.
    But working with the MEGA-65 team is a great pleasure and motivation.
    I'll continue and am looking forward to get in some future my own MEGA-65
    hardware.

    @Edilbert: 190 pages - very impressive! Amazing work! It's simple to start a chapter most of the time but it is hard to finish writing a chapter. And a chapter of 190 pages is more like a book than a chapter. This is stunning. And it requires a lot of discipline especially as the creative freedom is limited by avoiding copyright issues. This makes appetite for learning Basic 10... :thumbsup:

    Snoopy: at the moment, you would need to compile it yourself, since it is still in the works. (more than 400 pages now) and we use LaTex to create it. Of course, the manual will be available as a PDF once it's completed.

    Zitat von adtbm

    Snoopy: at the moment, you would need to compile it yourself, since it is still in the works. (more than 400 pages now) and we use LaTex to create it. Of course, the manual will be available as a PDF once it's completed.

    Many thanks for the fast answer!


    I'll compile the chapter for my first experiences in BASIC 10.


    If the final PDF is available, I'll download the whole MEGA65 manual then.


    Many thanks to Edilbert for his work on the BASIC 10 documentation! :thanx:

    It is open source, so if you want, you can redistribute it, but we would like to ask you, if you do, to explicitly inform the people:

    - that this document is work-in-progress and possibly subject to change !

    - and that the people who use it accept the GNU Free Documentation License

    ( This reference guide is made available under the GNU Free Documentation License v1.3,

    or later, if desired. This means that you are free to modify, reproduce and redistribute this

    user guide, subject to certain conditions. The full text of the GNU Free Documentation

    License v1.3 can be found at https://www.gnu.org/licenses/fdl-1.3.en.html.)


    Best thing is, to label it with the date of compiling, so it's easier to update later in this Thread as the manual gets bigger...

    (maybe something like: MEGA65manual_06-11-19.pdf)


    Also we would welcome everybody who reads through and spots an Error to drop a note here. this makes it easier for us to eliminate

    typos, errors, etc...

    Please use this thread for reporting errors, suggestions, ideas, comments.

    For questions regarding programming, etc., we would like to ask, to open a new Thread.

    This makes our life a bit easier.


    And Thanks ! nice to hear, that you like the manual. It was our intention to recreate the Retro-feeling ;-)


    PS: Did i already mention, that we are still looking for volunteers who want to help us, writing the manual ??? ;-)

    I have added a cover page with all these infos to the attached user guide.


    Because I can only upload files smaller than 2 MB, I have to compress the PDF file a little, but it is still clearly readable.

    unfortunately, the frontcover graphic is nearly completely out of frame, and the whole table of contents (with bookmarks) is missing (as well as the smaller table of contents in each chapter).


    I can see nothing wrong in the frontcover.tex:

    Code
    1. \node[anchor=north east,xshift=0.2cm,yshift=0.1cm]{\includegraphics[height=210mm,width=149mm]{frontcover/manual_title}};

    but I can reproduce both the frontcover problem and the missing tables of content when buiding it with mingw32 and TeX Live :nixwiss:


    [edit] interesting, if I build it again, the frontpage and the main ToC are fine. the ToCs of the chapters are not...

    Zitat von Yan_B

    [edit] interesting, if I build it again, the frontpage and the main ToC are fine. the ToCs of the chapters are not...

    Thanks for the feedback. I build the user guide a second time (Xubuntu / LaTeX) and now I can see the whole frontpicture with the TOC.


    I attached the update (2019-11-06) here.

    Zitat von Snoopy
    Zitat von Yan_B

    [edit] interesting, if I build it again, the frontpage and the main ToC are fine. the ToCs of the chapters are not...

    Thanks for the feedback. I build the user guide a second time (Xubuntu / LaTeX) and now I can see the whole frontpicture with the TOC.


    I attached the update (2019-11-06) here.

    LaTeX must always been run twice, in order to build a correct TOC (Table Of Contents).

    The missing TOC's on the chapter front pages is a known issue and will be fixed.


    Edilbert

    I make some first little tests with the BASIC 10 commands and I think, I have found a error in the command FOREGROUND:



    The color codes in the manual are not the colors seeing on the screen (XEMU emulator).


    I wrote a litte test program that shows all FOREGROUND colors (0 to 15):


    Color 0 is not display. There is a error message after trying FOREGROUND 0:


    Changing the FOR loop to starting with I=1:


    gets this result:


    The color index in the manual seems to be shifted one digit:


    0 doesn't work (error message)

    1 is black

    2 is white

    ...and so on ...

    Zitat von Bit Shifter

    LaTeX must always been run twice, in order to build a correct TOC (Table Of Contents).

    I have seen cases, where the 2nd run made the numbers appear, but only after the 3rd LaTeX got them correct :)

    BTW, maybe you could commit the current manual in PDF once per few weeks? It needs quite some environment to get it created, and most people aren't familiar with LaTeX at all.

    Thanks for the feedback Snoopy, we will forward the information.

    This is exactly the support we are looking for. we already suspected, that Commodore changed some of the BASIC

    commands from their draft manual, to the last Kernel, they have released. This will help us getting the BASIC commands correct and update the manual.

    THANKS !

    This is interesting!

    Is the colour table in the manual wrong or the implementation in the Commodore ROM or is it an emulator problem?

    The colour table, that I wrote into the manual, coincides with the available C65 documentation and the C128 and C64 tables.

    So I think, Commodore planned to be compatible. If there is this from Snoopy reported shift, we should correct that in the Kernal or BASIC ROM.

    Zitat von FeralChild
    Zitat von Bit Shifter

    LaTeX must always been run twice, in order to build a correct TOC (Table Of Contents).

    I have seen cases, where the 2nd run made the numbers appear, but only after the 3rd LaTeX got them correct :)

    BTW, maybe you could commit the current manual in PDF once per few weeks? It needs quite some environment to get it created, and most people aren't familiar with LaTeX at all.

    If the MEGA team agrees, I add a userguide.pdf to the repository, which will be updated on changes to the LaTeX source.

    Edilbert

    Zitat von Bit Shifter

    The colour table, that I wrote into the manual, coincides with the available C65 documentation and the C128 and C64 tables.

    So I think, Commodore planned to be compatible. If there is this from Snoopy reported shift, we should correct that in the Kernal or BASIC ROM.

    Using color numbers in the 1..16 range is compatible to BASIC 3.5 and BASIC 7. But BASIC 10 changes the syntax of all graphics commands anyway, so why not change this as well? Unless you want to stay true to how the C65 did it...

    Zitat von Mac Bacon
    Zitat von Bit Shifter

    The colour table, that I wrote into the manual, coincides with the available C65 documentation and the C128 and C64 tables.

    So I think, Commodore planned to be compatible. If there is this from Snoopy reported shift, we should correct that in the Kernal or BASIC ROM.

    Using color numbers in the 1..16 range is compatible to BASIC 3.5 and BASIC 7. But BASIC 10 changes the syntax of all graphics commands anyway, so why not change this as well? Unless you want to stay true to how the C65 did it...

    I compared the C128 manual and the preliminary C65 manual.

    C128 BASIC 7.0 has a colour range 1 -> 16

    C65 preliminary manual 0 -> 15

    Snoopy's test showed for the C65: 1 -> 16

    So I think, I should indeed choose the smartest way and change the manual.

    Thanks Snoopy and Mac Bacon for the hints.

    Edilbert

    Zitat von Bit Shifter

    Is the colour table in the manual wrong or the implementation in the Commodore ROM or is it an emulator problem?

    I can test the command only with the Xemu emulator.


    If it helps for the search of the error source, I list my enviroment for the test:


    I use Windows 7 (64 bit).


    Xemu command output:

    Code
    1. WINDOWS: console is open
    2. **** The Incomplete Mega-65 emulator from LGB ****
    3. This software is part of the Xemu project: https://github.com/lgblgblgb/xemu
    4. CREATED: lgb@oxygene on Linux 4.15.0-56-generic at Wed Jul 31 20:13:30 CEST 2019
    6. CREATED: mingw64 7.3-win32 20180312 64LE for win64
    7. VERSION: git@github.com:lgblgblgb/xemu.git dev ba27df64be8f5f30ce609816971dbc718
    8. b744f3a
    9. EMULATE: MEGA65 (mega65): xmega65 (../../build/bin/xmega65.win64) for mega65 on
    10. win64 using x86_64-w64-mingw32-gcc

    And the start screen of the Xemu is:



    Code
    1. BASIC 10.0 V0.9.910111