2023-02-14 17:44:00

6 files changed, 343 insertions, 0 deletions

diff --git a/doc/context/documents/general/manuals/canbedone-periods.pdf b/doc/context/documents/general/manuals/canbedone-periods.pdf
new file mode 100644
index 000000000..0a292735d
--- /dev/null
+++ b/doc/context/documents/general/manuals/canbedone-periods.pdf
diff --git a/doc/context/sources/general/manuals/canbedone/canbedone-periods.tex b/doc/context/sources/general/manuals/canbedone/canbedone-periods.tex
new file mode 100644
index 000000000..3ddb4545c
--- /dev/null
+++ b/doc/context/sources/general/manuals/canbedone/canbedone-periods.tex
@@ -0,0 +1,157 @@
+% language=us runpath=texruns:manuals/canbedone
+
+\environment canbedone-style
+
+% \showframe
+
+\startdocument
+  [title=periods,
+   color=middlered]
+
+\startsectionlevel[title=Introduction]
+
+When the \TEX\ program showed up there were not many fonts that could be used so
+it came with its own fonts and because the number of slots in the encoding was
+limited (first to 127, later to 255) there was no space characters. It was not
+needed anyway because the engine uses a model of glue between words. So, instead
+of fixed spacing, \TEX\ uses flexible spacing. In addition to what is normally
+considered a word space, spacing is also determined by the so called space factor
+of characters preceding spaces. But, especially after abbreviations with periods
+you might want something different depending on the usage of the period. Here we
+discuss how that can be done.
+
+\stopsectionlevel
+
+\startsectionlevel[title=Font related spacing]
+
+Spacing is controlled by the amount specified in the font in the so called
+font dimensions. In \CONTEXT\ these can be accessed via macros:
+
+\starttabulate[||c|c|c|c|]
+\BC                        \NC \tf normal space
+                           \NC \bf bold space
+                           \NC \it italic space
+                           \NC \bi bolditalic space                    \NC \NR
+\NC \tex{interwordspace}   \NC {\tf \expandafter}\the\interwordspace
+                           \NC {\bf \expandafter}\the\interwordspace
+                           \NC {\it \expandafter}\the\interwordspace
+                           \NC {\bi \expandafter}\the\interwordspace   \NC \NR
+\NC \tex{interwordstretch} \NC {\tf \expandafter}\the\interwordstretch
+                           \NC {\bf \expandafter}\the\interwordstretch
+                           \NC {\it \expandafter}\the\interwordstretch
+                           \NC {\bi \expandafter}\the\interwordstretch \NC \NR
+\NC \tex{interwordshrink}  \NC {\tf \expandafter}\the\interwordshrink
+                           \NC {\it \expandafter}\the\interwordshrink
+                           \NC {\bi \expandafter}\the\interwordshrink
+                           \NC {\bf \expandafter}\the\interwordshrink  \NC \NR
+\stoptabulate
+
+The differences in the three components are subtle but often of no concern to the
+user. Stretch and shrink kicks in when we align the left and right edge,
+otherwise they are basically ignored. These spacing properties are very specific
+for \TEX\ fonts, they don't come with for instance \OPENTYPE\ fonts. There we
+derive the stretch and shrink from the regular font space (\UNICODE\ slot U+00020
+or \ASCII\ value 32).
+
+A user can tweak the interword spacing with \type {\spaceskip} and \type
+{\xspaceskip} which works together with the \type {\spacefactor} and (character
+specific)\type {\sfcode} values. And as it is somewhat hard to explain the
+details involved I just refer to Chapter~25 (Spacing) of \TEX\ by Topic.
+
+\stopsectionlevel
+
+\startsectionlevel[title=Spacing after periods]
+
+For this manual it's only important to know that the space factors influence the
+spacing after uppercase letters and punctuation and the later aspect is what this
+is about.
+
+\startbuffer[a]
+\frenchspacing          This is a t.e.s.t. for periods. Does it work?
+\vskip-.8\lineheight
+\nonfrenchspacing \blue This is a t.e.s.t. for periods. Does it work?
+\stopbuffer
+
+\startbuffer[b]
+\frenchspacing           This is a t.e.s.t.\ for periods. Does it work?
+\vskip-.8\lineheight
+\nonfrenchspacing \green This is a t.e.s.t.\ for periods. Does it work?
+\stopbuffer
+
+\startbuffer[c]
+\frenchspacing         This is a t.e.s.t\fsp. for periods. Does it work?
+\vskip-.8\lineheight
+\nonfrenchspacing \red This is a t.e.s.t\fsp. for periods. Does it work?
+\stopbuffer
+
+\startbuffer[d]
+\setperiodkerning[zerospaceperiods]
+\frenchspacing         This is a t.e.s.t. for periods. Does it work?
+\vskip-.8\lineheight
+\nonfrenchspacing \red This is a t.e.s.t. for periods. Does it work?
+\stopbuffer
+
+\typebuffer[a] \start \forgetall \resetperiodkerning \getbuffer[a] \stop
+
+You will notice that the spacing after \type {t.e.s.t.} is as flexible as
+the space after \type {periods.} but what if you don't want that? There are
+several ways to influence the following space:
+
+\typebuffer[b] \start \forgetall \resetperiodkerning \getbuffer[b] \stop
+
+The \type {\fsp} macro looks ahead and adapts the space factor:
+
+\typebuffer[c] \start \forgetall \resetperiodkerning \getbuffer[c] \stop
+
+\stopsectionlevel
+
+\startsectionlevel[title=Automation]
+
+Where the manual (explicit) making sure we get spacing right is quite
+robust and predictable a user might be willing to delegate the task to
+\CONTEXT, and here is the trick:
+
+\typebuffer[d] \start \forgetall \resetperiodkerning \getbuffer[d] \stop
+
+This features has been present from mid 2017 but I admit that till now I never
+used it. Reasons are that it makes no sense to adapt existing documents and when
+a text is for instance meant for a user group journal too, you cannot expect this
+automatic feature to be present in the macro package used for typesetting it. But
+maybe it's time to change that policy. I also admit that I seldom have this
+situation, probably the only few cases are abbreviations like \type {e.g.} (for
+example) and \type {c.q.} (casu quo).
+
+There are a few predefined period kerning variants and you can define more if you
+want:
+
+\starttyping
+\defineperiodkerning [zerospaceperiods]  [factor=0]
+\defineperiodkerning [smallspaceperiods] [factor=.25]
+\defineperiodkerning [halfspaceperiods]  [factor=.5]
+\stoptyping
+
+\startbuffer[e]
+\setperiodkerning[zerospaceperiods]
+\frenchspacing         How about c.q. and e.g. within a sentence?
+\vskip-.8\lineheight
+\nonfrenchspacing \red How about c.q. and e.g. within a sentence?
+\stopbuffer
+
+\typebuffer[e] \start \forgetall \getbuffer[e] \stop
+
+Of course one needs to keep an eye on the results because one never knows if the
+heuristics are flawed. And if needed it can be improved.
+
+\stopsectionlevel
+
+\startsectionlevel[title=Todo]
+
+{\em more spacing related features}
+
+% optionalspace
+% autoinsertspace
+% ~
+
+\stopsectionlevel
+
+\stopdocument
diff --git a/doc/context/sources/general/manuals/canbedone/canbedone-style.tex b/doc/context/sources/general/manuals/canbedone/canbedone-style.tex
new file mode 100644
index 000000000..bbcb6b46a
--- /dev/null
+++ b/doc/context/sources/general/manuals/canbedone/canbedone-style.tex
@@ -0,0 +1,142 @@
+% language=us runpath=texruns:manuals/canbedone
+
+% I started this series in June 2023 when I found for the n\high{th} time that we
+% already had a feature that users requested in the mailing list, but that I had
+% completely forgotten about it being around for about 6 years.
+
+\startenvironment canbedone-style
+
+\usemodule[abbreviations-logos]
+\usemodule[scite]
+
+\setvariables
+  [document]
+  [title=No Title,
+   author=No Author,
+   color=NoColor]
+
+\setupbodyfont
+  [dejavu,11pt]
+
+\setuplayout
+  [width=middle,
+   height=middle,
+   backspace=2cm,
+   topspace=15mm]
+
+\setupwhitespace
+  [big]
+
+\setuphead
+  [chapter]
+  [style=\bfc,
+   color=darkgray]
+
+\setuphead
+  [section]
+  [style=\bfb,
+  %page=right,
+   color=darkgray]
+
+\setuphead
+  [subsection]
+  [style=\bfa,
+   color=darkgray]
+
+\setuplist
+  [chapter]
+  [style=bold]
+
+\setupfootertexts
+  [section] % [\documentvariable{title}]
+
+\setupfooter
+  [style=bold,
+   color=darkgray]
+
+\startuseMPgraphic{titlepage}
+    fill Page
+        withcolor "\documentvariable{color}" ;
+
+    numeric d ; d := 2mm ;
+
+    picture p ; p := textext.llft("!") ;
+    p := p
+        rotatedaround(llcorner p, 30) % different from lowlevel
+        xysized (.1PaperWidth-2d,.1PaperHeight-2d)
+        shifted (.1PaperWidth- d,.1PaperHeight -d)
+        shifted (d,-2d) % different from lowlevel
+    ;
+
+    draw image (
+        for i = 0 step .1 PaperWidth until PaperWidth :
+            for j = 0 step .1 PaperHeight until PaperHeight :
+                draw p shifted (i,j) ;
+            endfor ;
+        endfor ;
+    ) withcolor .4resolvedcolor("middlegray") ; % different from lowlevel
+
+    draw textext.d("\strut it can be done")
+        xsized (.8PaperWidth)
+        shifted center topboundary Page
+        shifted -(0,.2PaperHeight)
+        withcolor "white" ;
+  % draw textext.d("\strut YES")
+    draw textext.d("\strut \TeX")
+        xsized (.4PaperWidth)
+        shifted center topboundary Page
+        shifted -(0,.4PaperHeight)
+        withcolor "white" ;
+    draw textext.d("\strut\documentvariable{title}")
+        ysized 3cm
+        shifted center bottomboundary Page
+        shifted (0,.1PaperHeight)
+        withcolor "white" ;
+\stopuseMPgraphic
+
+\definesectionlevels
+  [default]
+  [%{chapter,title},
+   {section,subject},
+   {subsection,subsubject},
+   {subsubsection,subsubsubject},
+   {subsubsubsection,subsubsubject},
+   {subsubsubsubsection,subsubsubject}]
+
+\startsetups document:start
+
+    \startMPpage
+    StartPage;
+        \includeMPgraphic{titlepage} ;
+    StopPage;
+    \stopMPpage
+
+    \page
+
+    \startsubjectlevel[title=Contents]
+        \placelist[chapter,section] [criterium=previous]
+    \stopsubjectlevel
+
+\stopsetups
+
+\startsetups document:stop
+
+\testpage[6]
+
+%startsubjectlevel[title=Colofon]
+\startsectionlevel[title=Colofon,number=no,saveinlist=no]
+
+    \starttabulate
+        \NC Author      \NC Hans Hagen         \NC \NR
+        \NC \CONTEXT    \NC \contextversion    \NC \NR
+        \NC \LUAMETATEX \NC \texengineversion  \NC \NR
+        \NC Support     \NC www.pragma-ade.com \NC \NR
+        \NC             \NC contextgarden.net  \NC \NR
+    \stoptabulate
+
+\stopsectionlevel
+%stopsubjectlevel
+
+\stopsetups
+
+\stopenvironment
diff --git a/doc/context/sources/general/manuals/canbedone/canbedone.tex b/doc/context/sources/general/manuals/canbedone/canbedone.tex
new file mode 100644
index 000000000..6a2442f63
--- /dev/null
+++ b/doc/context/sources/general/manuals/canbedone/canbedone.tex
@@ -0,0 +1,29 @@
+% language=us runpath=texruns:manuals/canbedone
+
+\environment canbedone-style
+
+%D This is a bit if a cheat. The can be done manuals are independent but I want an
+%D overview document on the website. Therefore we use sectionlevels in the documents
+%D that we we then overload here (we push the chapter level in front).
+%D
+%D This style is mostly the same as the low level style.
+
+\starttext
+
+    \definesectionlevels
+      [default]
+      [{chapter,title},
+       {section,subject},
+       {subsection,subsubject},
+       {subsubsection,subsubsubject},
+       {subsubsubsection,subsubsubject},
+       {subsubsubsubsection,subsubsubject}]
+
+    \startdocument[title=canbedone,color=middlegray]
+    \stopdocument
+
+    \startsectionlevel[title=Periods] \component [canbedone-periods] \stopsectionlevel
+
+\stoptext
+
+
diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex
index 00a438781..83e43818f 100644
--- a/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex
+++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex
@@ -924,6 +924,17 @@ the hexadecimal numbers makes sense. It is unlikely that the core of \CONTEXT\
 will use this option but sometimes at the user level it can be handy. The penalty
 in terms of performance can be neglected.
 
+\starttyping[option=TEX]
+\tolerant\def\foo#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=%
+  {(#1)(#2)(#3)(#4)(#5)(#6)(#7)(#8)(#9)(#A)(#B)(#C)(#D)(#E)(#F)}
+
+\foo{1}{2}
+\stoptyping
+
+In the previous example we have 15 optional arguments where braces are mandate
+(otherwise we the scanner happily scoops up what follows which for sure gives some
+error).
+
 \stopsectionlevel
 
 \startsectionlevel[title=Constants]
diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel.tex
index 10057b999..2d6898835 100644
--- a/doc/context/sources/general/manuals/lowlevel/lowlevel.tex
+++ b/doc/context/sources/general/manuals/lowlevel/lowlevel.tex
@@ -20,6 +20,8 @@
     \startdocument[title=lowlevel,color=middlegray]
     \stopdocument
 
+    % this list is incomplete
+
     \startsectionlevel[title=Conditionals] \component [lowlevel-conditionals] \stopsectionlevel
     \startsectionlevel[title=Boxes]        \component [lowlevel-boxes]        \stopsectionlevel
     \startsectionlevel[title=Expansion]    \component [lowlevel-expansion]    \stopsectionlevel
@@ -35,6 +37,8 @@
     \startsectionlevel[title=Inserts]      \component [lowlevel-inserts]      \stopsectionlevel
     \startsectionlevel[title=Localboxes]   \component [lowlevel-localboxes]   \stopsectionlevel
     \startsectionlevel[title=Loops]        \component [lowlevel-loops]        \stopsectionlevel
+    \startsectionlevel[title=Tokens]       \component [lowlevel-tokens]       \stopsectionlevel
+    \startsectionlevel[title=Buffers]      \component [lowlevel-buffers]      \stopsectionlevel
 
 \stoptext