Skip to content

Instantly share code, notes, and snippets.

@claudio-naoto
Created January 5, 2021 10:13
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save claudio-naoto/419285013ee08714b0f6c3db62b02c91 to your computer and use it in GitHub Desktop.
Save claudio-naoto/419285013ee08714b0f6c3db62b02c91 to your computer and use it in GitHub Desktop.
English translation of demo.saty
@require: stdjabook
@require: code
@require: itemize
@require: tabular
@require: proof
@import: local
document (|
title = {An outline of \SATySFi;};
author = {Takashi SUWA};
show-title = true;
show-toc = true;
|) '<
+section{Starting}<
+p{
\href(`https://github.com/gfngfn/SATySFi`){\dfn{\SATySFi;}} is a new typesetting processing system result of an exploration project from IPA (Information-technology Promotion Agency, Japan) in 2017.
There are two kinds of typesetting processing systems:
\listing{
* GUI editors that previews the current state of the document \dfn{WYISIWYG} (What You See Is What You Get)
* batch systems, where the document is described as a text file in a \dfn{Markup language} and it is a input
to the language processing system, that outputs the final typesetted document in PDF or other format
}%
\SATySFi; is in the last category. Others software in this category are \LaTeX; and troff.
What is the difference of \SATySFi; from existing markup language processors, such as \LaTeX;?
To put it simply, the biggest differences are:
\listing{
* The code used to define and describe the commands is \emph{highly readable and easy to customize}
* \emph{Error reporting is presented quickly and clearly} when a user gives bad input
}%
Before we go into the details, let's take a closer look at the motivation for implementing \SATySFi;.
I want to explain it step by step.
}
+p{
What is better, the markup language method or the WYSIWYG method?
There are defenders for both methods.
However, it may be said that there is actually a trade-off between advantages and weaknesses in each method.
As for general advantages of the markup language method compared to the WYSIWYG method:
\listing{
* Since the input is a text file, difference management is easy
* User-defined commands allow you to:
** Complex automated processing
** Flexible appearance changes later without changing the content of the document
}%
On the other hand, the obvious weakness is:
\listing{
* Arbitrary text can be passed as input, so it is easy for the user to input wrong code.
}%
Of the wrong inputs from the user, when the code is suitable for the processing system,
in principle the system cannot detect mistakes (at least with non-statistical methods),
and the user must detect mistakes himself looking at the printed version.
For code that is not suitable to the processing system, this can be done.
In other words, the processing system should find and report mistakes such as incorrect command argument assignment.
The weakness is that it is easy for the user to give unintended code.
In certain markup language systems, code that is not suitable for the processing system is accepted as input.
I think that what kind of error reporting will have a great impact on the user's writing efficiency.
}
+p{
However, in existing processing systems of the markup language method, error reports of not well formed input
tend to be difficult to understand. For example, in the case of LATEX,
there are many users who have seen countless error logs like this:
}
+console(`! Undefined control sequence.`);
+console(`! Missing $ inserted.`);
+console(`! Missing number, treated as zero.`);
+pn{
In some cases, the cause may be immediately known, but basically:
"Inconsistency occured during the typesetting process".
Since the mechanism is such that an error is reported when it "occurs", the command that caused it is unknown to the user.
Errors are often reported due to inconsistencies between the description of the implementation and the arguments given.
"Something is wrong up to the nth line"
In many cases, you can only get information like that, and when this happens, there is no choice but to search for an error using binary search commenting the code out and identify the location of the cause.
}
+p{
Finally, returning to the main topic, \SATySFi; is one answer to solve these problems.
Specifically, because it is designed based on a language that is convenient for so-called functional programming:
\listing{
* having \emph{strong types}
* You \emph{only have to pay attention to local processing} without being aware of the global state.
}%
It is possible to enjoy the benefits of the knowledge of the function type, such as, error reporting has been strengthened in the form of type inspection.
}
+p{
Anyway, the error reporting ability is put aside for the time being, and what function is realizes in a typesetting processing system is touched in the chapter \ref(`sec:typesetting`);.
}
>
+section ?:(`sec:typesetting`) {Typical features}<
+subsection{European typesetting}<
+p{
Character glyphs have positive width, and paper has a finite width. Obviously, simply arranging the characters horizontally will not fit on the paper, so you have to start a new line somewhere. This line division process is essential when forming a column.
}
+p{
In European and more generally "alphabetic" typesetting, it is customary to divide lines somewhere in the space between words and justify the length of each line.
In addition to the white space between words, in some cases \dfn{hyphenation}, that is, a process of inserting a hyphen in a word to divide the line, is performed.
}
+p{
Regarding this European typesetting, \SATySFi; follows the processing methods
of the great pioneer \TeX;, and performs the line division processing
with an algorithm called the \dfn{Knuth–Plass algorithm} [Knuth 1978].
It also automatically add hyphenation to words to splits lines if necessary.
The place where a hyphen can be inserted is determined for each word by a method called
the \dfn{Liang–Knuth algorithm} that uses a dictionary of hyphen patterns [Liang 1983],
which is also installed in the \TeX; processing system.
\SATySFi; follows this and makes the same processing.
}
+p{
Let's take a look at some European languages texts actually composed by \SATySFi; below.
You can see that there are some ligatures and automatic hyphenation:
}
+paragraph-frame<
+p-latin{
The quick brown fox jumps over the lazy dog.
¿But aren’t Kafka’s Schloß and Æsop’s Œuvres often
naïve vis-à-vis the dæmonic phœnix’s official rôle
in fluffy soufflés?
}
+p-latin{
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua.
Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit
in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident,
sunt in culpa
qui officia deserunt mollit anim id est laborum.
}
>
>
+subsection{Japanese typesetting}<
+p{
In Japanese typesetting is customarily to arrange characters based on squares, and basically it is okay to start a new line in the middle of a word, which seems to be a slightly looser typesetting rule than European typesetting.
Many parts of this document (original japanese document) are written in Japanese, and the Japanese typesetting will be familiar to those who can read it.
However, visual adjustments such as how large a space should be before and after parentheses and punctuation marks are not so obvious.
In addition, no matter how tolerant the line break position is, for example, dividing
"chocolate"「チョコレート」 into lines between "chi"「チ」 and "okolate"「ョコレート」
or dividing it into "chocole"「チョコレ」 and "toto"「ート」 strongly arouses a sense of discomfort.
Therefore, arrangements such as \dfn{line-end prohibited characters} and \dfn{line-start prohibited characters} are required.
}
+p{
A document called \dfn{"Requirements for Japanese Typesetting"} (W3C Japanese Typesetting Task Force, 2012)
has been formulated as a summary of these rules, and is commonly known as \dfn{JLreq}.
\SATySFi; and the class files \file{stdja} and \file{stdjabook} are implemented to compose Japanese sentences in principle according to the Japanese typesetting rules defined in this JLreq, although not perfectly.
}
% +p{
% Specific examples are not given here. Fortunately, many parts of this document* are written in Japanese, and examples of typesetting results can be found everywhere.
% Please enjoy it by making sure that there are no spaces inserted between Japanese and European languages, and that there are no extra spaces at the end of lines ending with closing brackets or commas.
% *original japanese document
% }
% +p{
% In addition, Japanese typesetting can be typeset with good appearance without performing ligature processing and kerning processing as in European typesetting.
% And in fact \SATySFi; does not take into account the existence of ligatures in the processing of Japanese characters.
% However, in recent years, fonts with glyphs of Japanese characters with proportional character widths have appeared mainly for design intentions,
% and fonts that express continuous scripting by ligature processing have appeared, and I assume it will be necessary to deal with them in the future.
% }
>
+subsection{Image insertion function}<
+display-boxes('<
+p{
The logo is shown in Figure \ref(`fig:logo`); as proof that a image can be inserted.
\figure ?:(`fig:logo`){\SATySFi; logo}<
+image-frame{\insert-image(7cm)(`satysfi-logo.jpg`);}
>
}
>)(```
+p{
The logo is shown in Figure \ref(`fig:logo`); as proof that a image can be inserted.
\figure ?:(`fig:logo`){\SATySFi; logo}<
+image-frame{\insert-image(7cm)(`satysfi-logo.jpg`);}
>
}
```);
>
+subsection{Table}<
+p{
\SATySFi; also has a table layout function. The code is long, so I'll omit it.
}
+frame<
+centering{
\tabular(fun cellf multif empty -> [
[cellf {Program} ; multif 1 2 {Answer}; empty; multif 1 2 {Time [s]}; empty;];
[empty ; cellf {A}; cellf {B}; cellf {A}; cellf {B}];
[cellf {Program 1}; cellf {Yes}; cellf {Yes}; cellf {${0.004}}; cellf {${0.016}}];
[cellf {Program 2}; cellf {No} ; cellf {–} ; cellf {${0.004}}; cellf {–} ];
[cellf {Program 3}; cellf {Yes}; cellf {Yes}; cellf {${0.004}}; cellf {${0.078}}];
[cellf {Program 4}; cellf {Yes}; cellf {Yes}; cellf {${0.008}}; cellf {${0.069}}];
])(fun xs ys -> (
match (ys, List.reverse ys) with
| (y0 :: y1 :: y2 :: _, ylast :: _) ->
( match (xs, List.reverse xs) with
| (x0 :: x1 :: _ :: x3 :: _, xlast :: _) ->
let grlstY1 =
[y1; y2] |> List.map (fun y ->
stroke 0.5pt Color.black (Gr.line (x0, y) (xlast, y)))
in
let grlstY2 =
[y0; ylast] |> List.map (fun y ->
stroke 1pt Color.black (Gr.line (x0, y) (xlast, y)))
in
let grlstX =
[x1; x3] |> List.map (fun x ->
stroke 0.5pt Color.black (Gr.line (x, y0) (x, ylast)))
in
(stroke 0.5pt Color.black (Gr.line (x0, y1) (x1, y2)))
:: (List.append grlstX (List.append grlstY1 grlstY2))
| _ -> []
)
| _ -> []
));
}
>
>
+subsection{Numerical formula}<
+p{
One function of \LaTeX;, which is an existing typesetting system, is good at is outputting mathematical typesetting with overwhelming high quality.
With \SATySFi;, mathematical typesetting that can be said to be comparable to this has been realized. Let's try a few formulas:
}
+display-boxes('<
+math-list[
${F = G \frac{M m}{R^2}};
${\limto{N}{\infty} \sums{n = 1}{N} \frac{1}{n^2}
= \frac{\pi^2}{6}};
${\paren{\paren{\paren{A} + B} + C}};
${\brace{\brace{\brace{A} + B} + C}}
];
>)(```
+math-list[
${F = G \frac{M m}{R^2}};
${\limto{N}{\infty} \sums{n = 1}{N} \frac{1}{n^2}
= \frac{\pi^2}{6}};
${\paren{\paren{\paren{A} + B} + C}};
${\brace{\brace{\brace{A} + B} + C}}
];
```);
+display-boxes('<
+p{ The solution of the equation ${a x^2 + b x + c = 0}
as to ${x} is ${x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}}. }
>)(```
+p{ The solution of the equation ${a x^2 + b x + c = 0}
as to ${x} is ${x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}}. }
```);
+display-boxes('<
+math(
let int1 = ${\int_0^a} in
let int2 = ${\int_0^\sqrt{a^2 - x^2}} in
let sqrt2 = ${\sqrt{x^2 + r^2}} in
${
\frac{#int1 x \ordd x #int2 r #sqrt2 \ordd r}{
#int1 \ordd x #int2 r #sqrt2 \ordd r} = \frac{2a}{5} }
);
>)(```
+math(
let int1 = ${\int_0^a} in
let int2 = ${\int_0^\sqrt{a^2 - x^2}} in
let sqrt2 = ${\sqrt{x^2 + r^2}} in
${
\frac{#int1 x \ordd x #int2 r #sqrt2 \ordd r}{
#int1 \ordd x #int2 r #sqrt2 \ordd r} = \frac{2a}{5} }
);
```);
+display-boxes('<
+math(${
\derive{
| A | \derive{| B | C |}{D} |
}{E}
});
>)(```
+math(${
\derive{
| A | \derive{| B | C |}{D} |
}{E}
});
```);
>
>
>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment