iTranslated by AI
SATySFi Best Practices Roundup [Updated Regularly]
Introduction
With that in mind, this document might be of some help.
Notes
- These practices are based on SATySFi v0.0.7, which is the latest version as of April 2022.
- This article is still a work in progress. I plan to update it as circumstances change.
- Please feel free to point out any omissions or errors.
- Please understand that I may unintentionally favor my own packages.
Best Practices for Learning SATySFi
-
If you want to understand SATySFi thoroughly by reading a book, there is nothing better than The SATySFibook. Written by gfngfn, the developer of SATySFi, it is perfect for understanding the philosophy and syntax of SATySFi.
-
The documents located under doc/ in the official repository are useful for learning about more detailed features (such as all primitives).
However, you need to set up the SATySFi environment and compile them to read them. -
If you want to read many articles about SATySFi, try reading the SATySFi Advent Calendar articles.
Best Practices for When You Are Stuck with SATySFi
Ask someone for help. We recommend asking questions within the SATySFi community.
-
- A Slack community covering all topics related to SATySFi.
- It is divided into several channels, including a
#beginnerchannel where beginners can easily ask questions. - Specific code-related questions, which are difficult to handle on Twitter (due to character limits, etc.), are easier to conduct on Slack.
-
- Anyone can view and participate. Feel free to join if you have a Twitter account.
- Besides casually asking questions or consulting about SATySFi, it is also used for promoting packages.
Best Practices for Setting Up Development and Writing Environments
Environment Setup
For those who don't want to deal with the hassle of environment setup!
It might seem odd to have a sub-heading about "not setting up an environment" under the "Environment Setup" section, but there are actually two ways to use SATySFi without any local setup.
SATySFi Playground (https://www.satysfi-playground.tech)
- An environment where you can try SATySFi without creating an account or anything. You can use it just by visiting the URL above. The most convenient option.
- By using the URL displayed when generating a PDF, you can share the typesetting result with others.
- As of now, packages other than the standard ones cannot be used.
SATySFi Gitpod Template
- By using a service called Gitpod, you can use SATySFi in a VSCode-like online environment.
- SATySFi Workshop is included by default, enabling command completion and error diagnosis.
- You can install external packages using Satyrographos.
- While there are limits to the free tier of Gitpod, it should be sufficient for trial use.
For those who want to properly install SATySFi locally and write thoroughly!
Read the following article to set it up.
SATySFi Installation and Package Management
In most use cases, it can be said that managing packages with Satyrographos is the best choice.
Read the following article for usage instructions.
Writing Support by Editors
Depending on the text editor, extensions (plugins) that support SATySFi syntax may be available.
- VSCode: SATySFi Workshop
- Vim: qnighy/satysfi.vim: Vim syntax plugin for SATySFi typesetting system
- Emacs: gfngfn/satysfi.el: An Emacs major mode for SATySFi etc.
By using SATySFi language server, you can use smart command completion, definition jumps, and more.
It is included by default in SATySFi Workshop, and it can also be used in Vim or Emacs by configuring a language client.
Refer to the following article for detailed steps.
Best Practices for Creating Documents
Class Files
Class files in SATySFi refer to package files that define the entire framework for creating a document [1].
For example, if you want to use a class file named stdja, you would write the following at the beginning of your document file:
@require: stdja
There are roughly three types of class files:
- Built-in ones
stdjastdjabookstdjareportstandalone
- Not built-in, but registered in Satyrographos
exdesign-
jlreqetc.
- Not built-in and not registered in Satyrographos
It is easiest to use those that are "built-in" or "registered in Satyrographos."
You can check the list of class files available through Satyrographos on the Satyrographos Package Index.
By selecting a package, you can view various information such as basic details, installation methods, and documentation.
Reports and Books
When writing reports or books, there are several options to consider.
stdjabook
This is a class file for writing general documents.
Code Example
@require: stdjabook
document (|
title = {Title};
author = {monaqa};
show-toc = true;
show-title = true;
|) '<
+section{A Random Section}<
+subsection{A Random Subsection}<
+pn{
Paragraph 1.
}
+p{
Paragraph 2.
}
>
>
>
-
It is included in the standard distribution, so you don't need to install anything extra.
-
The following commands are defined:
-
+section,+subsection: Sections and subsections. -
\ref,\ref-page: Cross-references. -
\figure: Insertion of floating figures. -
+p,+pn: Paragraphs (+pndoes not have an indent at the beginning). -
\emph: Text emphasis. -
\footnote: Footnotes.
-
-
There is a similar class file called
stdja, but there are subtle differences, such as different layouts for chapters/sections and the fact thatstdjadoes not have the\footnotecommand for adding footnotes.
stdjareport
Compared to stdjabook, this class file is more suited for writing academic documents.
Code Example
@require: stdjareport
document (|
title = {Title};
author = {monaqa};
|) '<
+chapter{A Random Chapter}<
+section{A Random Section}<
+subsection{A Random Subsection}<
+p{
Paragraph 1.
}
+theorem?:({Random Theorem})?:(`foo`){A random claim.}
+proof{Left as an exercise for the reader.}
+corollary{A random corollary.}
+proof{ Obvious from Theorem \ref(`theorem:foo`);. }
>
>
>
>
- It is included in the standard distribution, so you don't need to install anything extra.
- In addition to the commands provided in
stdjabook, the following commands are defined:-
+chapter: Chapters. -
+definition,+theorem,+example,+lemma,+corollary: Definitions, theorems, examples, lemmas, and corollaries. -
+proof: Proofs. -
\dfn: Emphasis used for new terms, etc.
-
- Unlike
stdjabook, it does not include a table of contents feature.
exdesign
This is a class file where the appearance can be customized. Refer to the official documentation for typesetting examples.
You can flexibly specify the appearance by passing many items as arguments to the document function.
jlreq
This class file was developed by abenori, who is also the author of jlreq for LuaTeX-ja/pLaTeX/upLaTeX.
(As I am not an expert in Japanese typesetting, I cannot judge precisely, but) it is likely developed to meet the requirements of Japanese typesetting processing.
It provides commands equivalent to stdjabook and has extensive features for changing the appearance of document titles and tables of contents. Refer to the following for usage instructions:
Slides
SLyDIFi
This class file was developed for creating presentation slides. Unlike many other document classes, you can choose from multiple themes.
Also, you can change the appearance of the document using commands like +set-config instead of passing arguments to the document function.
See below for examples of typesetting and themes.
An explanatory article on creating slides using SLyDIFi is also available here:
Resume
This package can be used when creating a resume in SATySFi. Actual typesetting examples can be found in the repository's README.
Inserting Figures
In LaTeX's figure environment, you can insert figures as floating elements. In SATySFi, floating figures can also be handled depending on the class file, but currently, they cannot be specified as flexibly as in LaTeX. This is largely due to constraints in the SATySFi core, and improvements are expected in the future.
-
It is possible to insert a figure at a specific position within the text, regardless of the class file.
- This corresponds to "here" (
h) in LaTeX'sfigureenvironment.
- This corresponds to "here" (
-
Some class files allow you to display figures fixed at the top of a page.
- This corresponds to "top" (
t) in LaTeX'sfigureenvironment. - Commands named
\\figureoften correspond to this. - Supported class files include
stdjabookandjlreq.
- This corresponds to "top" (
-
Currently, no class file seems to provide features equivalent to "bottom" (
b) or "page" (p) in LaTeX'sfigureenvironment.- "Bottom" is theoretically possible and might exist if you search for it.
- Due to current SATySFi core constraints, achieving a "page" equivalent feature is difficult without updates to the core itself.
-
Inserting a figure at an "absolute position on the page" is possible regardless of the class file.
- This corresponds to the functionality of the
textpospackage in LaTeX.
- This corresponds to the functionality of the
If you want to insert a figure at a specific position in the text or at an absolute position on the page, the satysfi-figbox package is useful.
Refer to the manual for details on features and usage.
Inserting Tables
Use satysfi-easytable.
Text Decoration and Typeface Changes
Changing Typefaces
Currently, typeface settings for headings and other elements largely depend on the class file. While some provide official APIs, others require modifying the class file itself to change the typeface. It's a good idea to consider these factors when choosing a class file.
When changing the typeface of the main text, you can define your own commands or use the satysfi-fss package. It allows you to change font sets, weights, sizes, etc., with a simple API.
Ruby (Furigana)
satysfi-ruby is useful. It supports various features such as adjustment of intrusion and prohibition of protrusion.
Inserting Bibliographies
You can use BiByFi.
Best Practices for Creating SATySFi Packages
Repository Structure
Interface Design
Implementation
- The
satysfi-basepackage contains many functions useful for various processes. Let's use it actively.- Simply replacing the standard
listpackage withbase/list-extwill significantly expand the functions available to you.
- Simply replacing the standard
Registering to Satyrographos
Registering with Satyrographos makes your package much easier to use. The steps for distributing your own package via Satyrographos are described in the following article:
Best Practices for Contributing to SATySFi
I want to contribute to the new technology SATySFi! But I don't know where to start! In fact, there are many ways you can contribute to SATySFi.
Use SATySFi
Just using SATySFi and showcasing that you used it is a form of contribution. If you publish the source code, it's an even bigger contribution.
Participate in the Community
Join the SATySFi community and engage in discussions. Answering questions from beginners is also a great way to contribute.
Improve SATySFi Documentation
SATySFi is still a new tool, and there isn't much documentation yet. Simply improving the documentation would be a significant contribution.
-
Volunteers are writing a document called learn-satysfi, but currently, it lacks content due to a shortage of manpower. It would be very helpful if you could fill in even just the parts you understand.
-
Writing introductory or explanatory articles about SATySFi is also good. If you register them in an Advent Calendar, you can expect many readers.
Create SATySFi Packages or Send Issues/PRs to Existing Ones
Compared to TeX/LaTeX, SATySFi still lacks many packages. By adding various libraries, the chances of SATySFi being adopted will increase.
Also, sending pull requests for new features or reporting issues to existing packages is another form of contribution.
Add Features or Fix Bugs in the SATySFi Core
SATySFi is open-source, and anyone can submit pull requests for feature additions or bug fixes. For features that cannot be implemented just by adding or modifying packages, try contributing to the core itself.
Enhance SATySFi Ecosystem Tools
What makes SATySFi work is not just the core and the packages.
- Satyrographos: Package manager
- Satyrographos Package Index: Web UI for the package manager
- docker-satysfi: Docker image for SATySFi
- SATySFi playground: A playground to easily try it online
- SATySFi-related text editor extensions/language servers (mentioned above)
Almost all of these are developed by volunteers other than the core SATySFi developer. Contributions to these tools are nothing less than contributions to SATySFi itself.
Donate to Upgrade the Developer's Dinner
For those who want to contribute but don't have technical knowledge.
The SATySFibook is available for free download, but you can also purchase a donation version (300 yen). You can even add more to the amount.
The donation version is the same PDF as the free version, but purchasing it will encourage the author and make them happy by upgrading their dinner. Please consider it if you'd like.
So, if you're interested, please consider upgrading the dinner of the developer, gfngfn.
-
Generally, a function that receives information such as metadata and block text and returns a value of type
documentis the "core" of a class file. The package files where these are defined can be called class files. ↩︎
Discussion