Hallo Besucher, der Thread wurde 7,7k mal aufgerufen und enthält 81 Antworten

letzter Beitrag von mega65 am

Mega-Book - First aid for a LaTeX retiree

    Since my last bigger work with LaTeX was more than 20 years ago, my knowledge of this topic has fallen asleep and is probably out of date. :alt:


    Do you have any tips on how best to get back into the subject? Are there any IDEs (under Linux) that are recommendable or is a simple text editor still the method of choice?


    I want to see if and how I could manage to work something on the mega-book. I know the github page for it: github.com/MEGA65/mega65-user-guide


    But how I handle the book structure and how the individual TEX files are related, is not yet entirely clear to me. :search:


    What do I have to consider and what do I have to change, for example if I want to insert a new chapter?


    I would be very grateful for tips and hints on the subject! :baby2:

  • Snoopy

    Hat den Titel des Themas von „Mega-Book - First aid for a LaTex retiree“ zu „Mega-Book - First aid for a LaTeX retiree“ geändert.

    Hi Snoopy !


    The best persons to contact in regard of your question would be Bit Shifter or mega65.

    They can give you mor information how to build LaTex and what additional modules are needed.

    I've contacted the peeps at our discord channel, to have a look here in this thread.

    IDE: Back then (while studying at the university) I was using Kile (https://kile.sourceforge.io/), it seems it is still being developed. But for smaller project, without math equations, Kate should be enough. Regarding the best guide - AFAIK nothing has changed, and nothing beats The Not So Short Introduction to LaTeX (at least few years ago I found it very useful when I needed LaTeX for my job).

    Needed packages might depend on your Linux distro - I have installed (Gentoo Linux) the following:


    - app-text/texlive-core

    - dev-tex/latexmk

    - dev-texlive/texlive-xetext

    and it was enough (but I haven't tried to build the manual for a while, something might have changed since then).

    On my Debian based system:


    First install a TeX Live environment (beware: about 2.7 GB of data):

    Code
    1. jon@debian:~$ sudo apt-get install texlive-full

    Next i would suggest to use TeXstudio as an IDE:

    Code
    1. jon@debian:~$ sudo apt-get install texstudio

    Download a copy of the git repository:

    Code
    1. jon@debian:~$ git clone https://github.com/MEGA65/mega65-user-guide.git
    2. jon@debian:~$ cd mega65-user-guide/

    Use the sandbox.tex file (it's part of the git-content) for experimenting and testing with the IDE:

    Code
    1. jon@debian:~/mega65-user-guide$ texstudio sandbox.tex


    The configuration of TeXstudio, should be changed to use XeLaTeX:


    Click on the green "fast forward button" in the ide to build the sandbox.tex file (in the following picture a red circle marks the spot)



    In the example above the file sandbox.tex is the topmost one (hierarchically) and includes all other required files with the include{...} command. Running XeLaTeX (in the IDE with the green "fast forward button") while this file is open and active/selected in the IDE, the IDE will us XeLaTeX to produce the sandbox.pdf file.


    To add an own chapter or sections to the sandbox.pdf manual, you just need to create an own valid tex file in the same directory as sandbox.tex and include it - for example I create myChapter.tex and use the command include{myChapter} in the sandbox.tex file to include this file in the "build" process:



    The content of the file myChapter.tex could be very simple, but needs to contain valid LaTeX instructions, as an example:

    Code
    1. \chapter{My Chapter}
    2. \label{cha:my-chapter}
    4. My Chapter starts here
    6. \section{My Section}
    8. This is my section

    The topmost tex file for the mega65-book is the file mega65-book.tex and this file imports/includes/inputs the other parts of the book. It uses the LaTeX command input{...} to include the required content (this file does not use the slightly different include{} command):



    To add your own content to the book, just create an additional tex file myfile.tex (for example) with the content you like and use input{myfile} at the correct location in the file mega65-book.tex to include it there.


    The readme.md file in the git repository describes the usage of the linux make command to build the pdf file of the mega-book, rather than using an IDE. They provide the file sandbox.tex for testing and experimenting with an IDE.

    Snoopy : you are welcome. Hope it helps.


    As for the IDE: There are surely a lot of choices and they depend on the individual requirements and likes. I am suggesting TeXstudio because it is

    • open source
    • available for macOS, Linux and Windows
    • in development since 2009 (at leat) and still activly maintained

    Here you can find more informations about it: link to the homepage of the project.

    Well, basicly LaTeX has not changed that much in the last 20 years. For me the biggest difference was switching to xelatex from pdflatex which makes it much easier to use system fonts and much more.


    But these details should not really matter if you want to help with the Mega65 Book as you just add to everything that is already set-up there.


    Regarding a LaTeX IDE for Linux. It pains me a little since it is from Microsoft and based on Electron. But Visual Studio Code has really good LaTeX Plugins available (among other things) and is therefore my reccomendation!


    lg

    AndiS

    Probably easiest is to just produce CSV files with the memory map info, and I can latexify them to automatically generate the content, like we do for the register maps for the various chips.

    Other tables and things will take a bit more work, but its pretty straightforward to work on. We can do the typesetting here, if you don't want to have to install all the tools.


    LG

    Paul.

    Hi Snoopy!

    Sorry, I got the message from adtbm very late, because I was busy doing other work.

    But I see, that others jumped in to help.

    Good to see, that this community, interested in and working on MEGA65 stuff is so great.


    My recommendation for contributing to the manual is: Look at the source code of the existing chapters.

    You see many examples, how to arrange text, insert pictures and create nice looking tables.

    Typically each chapter is in a separate file, which is "input" in the main file.

    Take a look at the file "mega65-book.tex" which is the main file for the guide.


    The pdf building is controlled via makefile, I hope, that you are familiar with this.

    The guide uses references and an index, so you have to call the "make" command typically three times, until all references are solved.


    Large tables, like the 6502 and 45GS02 instructions for example are not written by hand, but are generated by C programs,

    which are also contained in the github repository. This makes it easier to handle large amounts of tables.


    Feel free to contact me for any question, I'm happy to help contributors.

    Also in German language, which is my native tongue.


    But I cant't help much regarding IDEs. I'm using LaTeX the old fashioned way:

    Editing the source code with the editor "vim" and calling Acrobat Reader to check the result.


    If you want my private email address, send a PM.


    Best wishes,

    Edilbert

    Zitat von hexfile

    On my Debian based system:

    ...

    hexfile : Many, many thanks for your detailed and great help! I've install texlive and texstudio and go through your described steps. All works fine without any problem! :thumbup:


    Only little thing, I've made beside your steps: I set the language to English in texstudio, so the spelling routine knows the english words used in the mega-book:




    So, now I can start with LaTeX. If you'll hear in the next time an explosion, maybe it's my LaTeX-Compiler
    who was angry about my first "crazy" LaTeX commands. :D


    Many thanks again! :thumbup:

    Zitat von Bit Shifter

    The pdf building is controlled via makefile, I hope, that you are familiar with this.

    Thanks for your answer! :thumbup:


    I'm familiar with the make command as a "usual" user, so I think that will be no problem.


    What I'm not so familiar in is the "git" command and environment. "git clone" and "git pull" I know for download and update a git rep.


    If I'd modified a tex file of the mega-book (e.g. correct some typos) or add a complete new chapter and think it'll be a benefit for the book, I have to use "git push" to contribute the changed file? Or how does it work, so there will be no "confusion" with different states of the files? :gruebel


    If you can give me a little help in this "git" topic, I would be glad. If it's ok for you, we can continue here in this thread, so maybe others, who want to help, can read all hints too. If you prefer a more private talk (in German), you can use my mail address: 65software@gmx.de


    Thanks for your help! :thumbup:

    Hi Snoopy,

    git is very easy to use. Either with a GUI client, which is available for Windows, Linux and MAC or with commands in a shell.

    I give here some examples with shell commands.

    Before starting any editing you should synchronise your local repository with:

    git pull

    Then you can edit, create or delete files as ou wish.

    Use your favourite editor or GUI for editing files.

    Use "git rm <filename>" for delete.

    Use "git add <filename>" to mark files, which should be updated or created on the repository.

    "git commit" checks your marked files and asks you to enter a comment, regarding the commitment.

    "git push" will upload all your changes to the repository.


    But this procedure will only work, if you have write permission for the repository.

    New contributors normally have no write permission.

    They have to create a "pull request" with their contribution.

    Then a user with write permission can look at your contribution and do a "merge", if she or he agrees with it.

    For details of "pull request" and "merge" please use the help system of github.

    Zitat von Snoopy
    Zitat von Bit Shifter

    Take a look at the file "mega65-book.tex" which is the main file for the guide.

    Is it correct, that a "make mega65-book.pdf" creates a PDF with 205 pages?


    The mega65-book I used in the Xemu live system (August) has more than 800 pages ... :gruebel

    No, that is not correct. Probably some LaTeX file is missing.

    Look at the error messages. I know, there are lot of warnings, but before stopping LaTeX should also report the fatal error messages.

    Zitat von Bit Shifter

    No, that is not correct. Probably some LaTeX file is missing.

    Look at the error messages. I know, there are lot of warnings, but before stopping LaTeX should also report the fatal error messages.

    I see, that were are some errors in the log.


    Here is the log of the 4th run of "make mega65-book.pdf":