TeXmacs notes

Contribution guide

The blog can be read offline within TeXmacs. Just open one of the documents in the source directory and click on the links: they point to the local .tm files. Browse back-forward with the buttons

and

on the top toolbar.

Typically it should just be necessary to modify or add to only the .tm sources in the src/ directory—and modify accordingly main.tm. The html files are then generated by one of the maintainers after the pull request is merged (hopefully this will be automated in the near future): for this reason, please do not add the locally-generated web pages (see below) to the git commits. Once the changes are pulled in they will become immediately publicly visible on the website.

To automatically regenerate all the web pages use →→ within TeXmacs and choose src/ as source and docs/ as destination directories. In this case, all links will become links to the local versions of the document and you will be able to browse them locally using a web-browser (as said above, the maintainers are going to take care of the conversion to html in the web site).

This template file can be used for new articles.

If you do not have commit rights (that is, write permission) on the repository, you can make a pull request starting from a fork of the repository.

It is necessary to perform a few actions using the terminal. The sequence is fork–clone–modify–add–commit–push and finally make a pull request. People that use Git are familiar with these commands. Here are some hints for those that are using Git for the first time. A basic tutorial on how to work on one's own repositories using Git is available at

Fork the repository at Github. This can be done through the web interface there. You need to have a Github account. This operation creates a complete copy of the main repository in your Github account.

Clone it locally. Within a suitable directory execute the command

git clone https://github.com/texmacs/notes.git

a subdirectory named notes will appear, where you will be able to work on the files. Now you have a complete copy of the main repository on your computer. You can browse the site also locally by pointing the browser to index.html.

Make your modifications locally.

Add the modified files to git (command git add).

Commit with git commit

the first time you do this, git might ask you to set your identity with the commands
```
git config --global user.email
```
and
```
git config --global user.name
```
the –global switch can be omitted; in this case the identity will be set for the current repository only.

Push the modifications to your forked repository using git push. Git might then ask for username and password.

Now you can make a pull request through the web interface, at

https://github.com/texmacs/notes/pulls

(green button New pull request). The web interface gives further helpful hints. Follow the link compare across forks above the pulldown menus to have them show forks, from which you can select yours.

The pull request on github asks the maintainers to integrate your changes into the public repository.

Go to step 3.

To keep your fork up to date:

Configure the upstream remote repository with

git remote add upstream https://github.com/texmacs/notes.git

Detailed instructions at:

https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork

Follow the steps at

https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork

that is:

Make sure you are working on the branch you want to work on, e.g.
```
git checkout main
```
where git might answer you
```
Already on 'main'
Your branch is up to date with 'origin/main'.
```

Then do

git fetch upstream
git merge upstream/main
git push

Please check also the editorial guidelines for preparing your content.