Merge pull request typst-doc-cn#27 from YDX-2147483647/more

docs: citation form, auto hanging indent, cjk-latin space at `\ `

Author: YDX-2147483647

README.md

@@ -58,7 +58,7 @@ A simple typst example.
 
   👀 shown as the source, but 🛑 not executed in the preview.
 
-#### Limitations
+#### Limitations and caveats
 
 Simple examples are evaluated in a container and their states are shared across the entire document.
 
@@ -72,9 +72,13 @@ As a result:
 
 - Citations and bibliographies will conflict with other examples.
 
+- The default configuration values are those specified in `raw`, which may differ from the defaults in regular documents.
+
+  For example, the default `text.cjk-latin-spacing` is typically `auto`, but here it is `none`.
+
 - …
 
-If you need advanced features, please write a page example instead.
+If you require advanced features or 100% accuracy, please write a page example instead.
 
 ### Page examples (`example-page`)
 

main.typ

@@ -1,6 +1,7 @@
-#import "typ/util.typ": babel, bbl, issue, note, prompt, pull, unichar, workaround
+#import "typ/packages/till-next.typ": mark-till-next, till-next
+#import "typ/util.typ": babel, bbl, issue, note, now-fixed, prompt, pull, unichar, workaround
 #import "typ/prioritization.typ": level, level-table
-#import "typ/show-example.typ": render-examples
+#import "typ/show-example.typ": layout-git-log, render-examples
 #show: render-examples
 
 #babel(en: [Chinese Layout Gap Analysis for Typst.], zh: [分析 Typst 与中文排版的差距。])
@@ -44,6 +45,7 @@
 
 #set heading(numbering: "1.1")
 #show heading.where(level: 3): set heading(numbering: none)
+#show: mark-till-next
 
 = #bbl(en: [Text direction], zh: [文本方向])
 
@@ -677,7 +679,7 @@
 ```
 
 ```example-page
->>> // This example behaves differently in `example` and `example-page`.
+>>> // This example behaves differently in `example` and `example-page` because of cjk-latin-spacing.
 >>> #set text(top-edge: "ascender", bottom-edge: "descender")
 >>> Current:
 #set par(justify: true)
@@ -816,6 +818,25 @@ $ integral f dif x $
 >>> 汉字#h(0.25em)$A$#h(0.25em)汉字
 ```
 
+=== #bbl(en: [Redundant CJK-Latin space at manual line breaks], zh: [人为换行时多余中西间距])
+
+#level.advanced
+#issue("typst#6539")
+
+#babel(
+  en: [If the line is manually broken between a CJK and a Latin character, then typst will insert an extra CJK-Latin space. This space becomes noticeable when text is aligned to the right or center.],
+  zh: [若在汉字和拉丁字母间手动换行，typst 会插入多余中西间距。如果文本右对齐或居中对齐，这个间距会显现出来。],
+)
+
+```example
+>>> Current: \
+#set text(cjk-latin-spacing: auto)
+#box(width: 3em, stroke: (right: green), align(right, [国国\ TT]))
+
+>>> Expected: \
+>>> #box(width: 3em, stroke: (right: green), align(right, [国国TT]))
+```
+
 === #bbl(en: [Punctuation compression is interrupted by `#show`], zh: [`#show`会打断标点挤压])
 
 #level.basic
@@ -957,6 +978,31 @@ $ integral f dif x $
 >>> = 一、标题
 ```
 
+=== #bbl(en: [The auto hanging indents of multiline headings are inaccurate], zh: [多行标题的自动悬挂缩进不准确])
+
+#level.advanced
+#issue("typst#6527")
+#workaround("https://github.com/typst/typst/issues/6527#issuecomment-3026200835")
+
+#babel(
+  en: [The default value of `heading.hanging-indent` is `auto`, which indicates that the subsequent heading lines will be indented based on the width of the numbering. However, the `auto` width is not accurate if the numbering ends with a full-width punctuation, e.g., #unichar("、").],
+  zh: [`heading.hanging-indent`默认为`auto`，表示标题从第二行起按编号的宽度缩进。然而若编号以全宽标点结尾，例如 #unichar("、")，那么`auto`得出的宽度并不准确。],
+)
+
+```example-page
+#set page(width: 5 * 12pt + 2 * 1em, margin: 1em)
+#show heading: set text(12pt)
+
+>>> #show heading: pad.with(top: -0.75em)
+>>> Current:
+#set heading(numbering: "一、")
+= 寻寻觅觅
+
+>>> Expected:
+>>> #set heading(numbering: none, hanging-indent: 2em)
+>>> = 一、寻寻觅觅
+```
+
 == Styling initials <initials>
 
 #prompt(from-w3c: "https://www.w3.org/TR/clreq-gap/#initials")[
@@ -1137,13 +1183,15 @@ $ integral f dif x $
 
 === #bbl(en: [Citation numbers are flying over their brackets], zh: [引用编号的数字高于括号])
 
-#level.basic
-#issue("typst#633")
+#level.ok
+#issue("typst#633", closed: true)
 #issue("typst#6513", closed: true)
 #issue("typst#4203", closed: true)
-#pull("typst#5777")
+#pull("typst#5777", merged: true)
 #workaround("https://typst-doc-cn.github.io/guide/FAQ/cite-flying.html")
 
+#till-next(now-fixed.with(last-affected: "0.13.1", last-level: "basic"))
+
 #babel(
   en: [The style `gb-7714-2015-numeric` formats a citation with a number enclosed in square brackets (e.g., `[1]`) and render them in superscript. However, some fonts only provide dedicated superscript glyphs for numbers, not for brackets. This can cause misalignment, with the numbers appearing higher than the brackets in the superscript.],
   zh: [`gb-7714-2015-numeric`样式会用括号包裹引用编号（例：`[1]`）并上标。不过有些字体只给数字提供了专用上标版本，而括号未提供。这导致上标时未对齐，数字显得比括号高。],
@@ -1232,7 +1280,7 @@ $ integral f dif x $
 
 ````example-page
 >>> Expected: \
-<<< 孔乙己@key，另见文献~#parencite(<key>)。
+<<< 孔乙己@key，另见#cite(<key>, form: "prose-short")。
 >>> 孔乙己#super[[1]]，另见文献#h(0.25em)#[[1]]。
 ````
 
@@ -1600,6 +1648,8 @@ $ integral f dif x $
   [
     - #bbl(en: [Document version], zh: [文档版本]) \
       #link(git.commit_url)[commit #git.name] (#link(git.log_url)[log])
+
+      #layout-git-log(summary: bbl(en: [Latest log], zh: [最新日志]), git.latest_log)
   ]
 }
 

netlify.toml

@@ -20,7 +20,7 @@ bash scripts/patch-htmldiff.sh
 [[headers]]
 for = "/assets/*"
 [headers.values]
-Access-Control-Allow-Origin = "https://services.w3.org" # Allow CORS for /htmldiff
+Access-Control-Allow-Origin = "*" # Allow CORS for https://services.w3.org/htmldiff
 
 
 [[plugins]]

scripts/build.ts

@@ -4,32 +4,51 @@ import { fileURLToPath } from "node:url";
 import { extraArgs } from "./config.ts";
 import { precompile } from "./precompile.ts";
 import { typst } from "./typst.ts";
-import { duration_fmt } from "./util.ts";
+import { duration_fmt, execFile } from "./util.ts";
+
+interface GitInfo {
+  name: string;
+  commit_url: string;
+  log_url: string;
+  /** latest git log */
+  latest_log: string;
+}
+
+async function git_info(): Promise<GitInfo | null> {
+  const git_log = execFile("git", [
+    "log",
+    "--max-count=1",
+    "--pretty=fuller",
+    "--date=iso",
+  ]).then(({ stdout }) => stdout.trim());
 
-function git_info(): string[] {
   if (env.GITHUB_ACTIONS === "true") {
     // https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
     const base = `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}`;
-    const info = {
-      name: `${env.GITHUB_SHA?.slice(0, 8)} (${env.GITHUB_REF})`,
+    return {
+      name: `${env.GITHUB_SHA?.slice(0, 8)} (${env.GITHUB_REF_NAME})`,
       commit_url: `${base}/commit/${env.GITHUB_SHA}`,
       log_url: `${base}/actions/runs/${env.GITHUB_RUN_ID}`,
+      latest_log: await git_log,
     };
-    return ["--input", `git=${JSON.stringify(info)}`];
   } else if (env.NETLIFY === "true") {
     // https://docs.netlify.com/configure-builds/environment-variables/
-    const info = {
+    return {
       name: `${env.COMMIT_REF?.slice(0, 8)} (${env.HEAD})`,
       commit_url: `${env.REPOSITORY_URL}/commit/${env.COMMIT_REF}`,
       log_url:
         `https://app.netlify.com/sites/${env.SITE_NAME}/deploys/${env.DEPLOY_ID}`,
+      latest_log: await git_log,
     };
-    return ["--input", `git=${JSON.stringify(info)}`];
   } else {
-    return [];
+    return null;
   }
 }
 
+function as_input(info: GitInfo | null): string[] {
+  return info ? ["--input", `git=${JSON.stringify(info)}`] : [];
+}
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   await precompile();
 
@@ -38,7 +57,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     "compile",
     "index.typ",
     "dist/index.html",
-    ...git_info(),
+    ...as_input(await git_info()),
     ...extraArgs.build,
   ]);
   console.log(

scripts/config.ts

@@ -23,7 +23,9 @@ export const extraArgs = {
     "mode=build",
     "--input",
     `x-url-base=${
-      env.NETLIFY === "true" ? "/" : (env.GITHUB_PAGES_BASE ?? "/clreq/")
+      env.NETLIFY === "true"
+        ? env.DEPLOY_URL + "/" // patch htmldiff, or assets will go to services.w3.org
+        : (env.GITHUB_PAGES_BASE ?? "/clreq/")
     }`,
     ...envArgs,
   ],

scripts/patch-htmldiff.sh

@@ -9,14 +9,6 @@ set -euxo pipefail
 # The commit version might be the following:
 # https://github.com/w3c/htmldiff-ui/blob/5eac9b073c66b24422df613a537da2ec2f97f457/htmldiff.pl
 
-# Set base.
-# Otherwise, CSS & JS will go to services.w3.org.
-#
-# This CGI-mode feature is missing in CLI mode.
-# https://github.com/w3c/htmldiff-ui/blob/5eac9b073c66b24422df613a537da2ec2f97f457/htmldiff.pl#L560-L563
-if [[ "${NETLIFY:-false}" == "true" ]]; then
-  sd --fixed-strings "<head>" "<head><base href='$DEPLOY_URL/'>" dist/index.html
-fi
 
 # Improve readability for `<pre>`.
 #

src/util.css

@@ -44,3 +44,44 @@ aside.note {
     color: var(--accent);
   }
 }
+
+/* `details.now-fixed` */
+details.now-fixed {
+  margin-block: 1em;
+  border-left: 3px solid var(--accent);
+  border-radius: 8px;
+  padding-inline-start: 1.5em;
+  padding-block: 0.5em;
+
+  > summary {
+    cursor: pointer;
+    margin-left: -0.5em;
+
+    display: grid;
+    grid-template-columns: auto 1fr;
+    align-items: center;
+
+    font-weight: bold;
+    color: var(--accent);
+
+    /* Replace ::marker with ::before */
+    list-style: none;
+
+    &::before {
+      display: block;
+      height: 2em;
+      width: 2em;
+    }
+
+    > p {
+      margin-top: 0;
+    }
+  }
+
+  > summary::before {
+    content: "▶";
+  }
+  &[open] > summary::before {
+    content: "▼";
+  }
+}

typ/packages/till-next.typ

@@ -0,0 +1,83 @@
+/// Apply a function to the following content until next heading or `#till-next`.
+///
+/// = Usage
+///
+/// == Input
+///
+/// ```
+/// #show: mark-till-next
+///
+/// A
+///
+/// #till-next(wrapper)
+///
+/// B
+///
+/// C
+///
+/// = Heading
+///
+/// D
+/// ```
+///
+/// == Equivalent output
+///
+/// ```
+/// A
+///
+/// #wrapper[
+///   B
+///
+///   C
+/// ]
+///
+/// = Heading
+///
+/// D
+/// ```
+///
+/// = Known behaviours
+///
+// - `#till-next` should be put at the same level of `#show: mark-till-next`, or it will be ignored.
+// - If you put two `#till-next` consecutively, then the former `#till-next` will receive a space `[ ]`, not `none`.
+#let till-next(fn) = metadata((till-next: fn))
+
+/// A show rule that makes `#till-next(fn)` effective.
+///
+/// Usage: `#show: mark-till-next`
+#let mark-till-next(body) = {
+  // The wrapper function
+  let fn = none
+  // The fenced elements to be wrapped
+  let fenced = ()
+
+  for it in body.children {
+    let is-the-metadata = it.func() == metadata and it.value.keys().contains("till-next")
+    let is-heading = it.func() == heading
+
+    if is-the-metadata or is-heading {
+      if fn != none {
+        // Complete the last fence
+        fn(fenced.join())
+        fn = none
+        fenced = ()
+      }
+      if is-the-metadata {
+        // Start a new fence
+        fn = it.value.till-next
+      } else {
+        it
+      }
+    } else if fn != none {
+      // Continue the fence
+      fenced.push(it)
+    } else {
+      it // if not in any fence
+    }
+  }
+
+  // Complete the last fence
+  if fn != none {
+    fn(fenced.join())
+  }
+}