Add a section about text formatting and show in a "TIP" how to use complex formatting.
PR: 262001
Details
Details
Diff Detail
Diff Detail
- Repository
- R9 FreeBSD doc repository
- Lint
Lint Skipped - Unit
Tests Skipped
Event Timeline
Comment Actions
For what it's worth, I'd refer to https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#text-formatting instead of enlarging a primer that is already, to my eye, way too large to be thought of as a primer …
Please, don't take this personally. Wherever I see the opposite of concise: I always think of extensive pruning, but I rarely share the thought …
| documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc | ||
|---|---|---|
| 157–159 | ||
| 193 | Closing what? | |
Comment Actions
haha, no problem :)
| documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc | ||
|---|---|---|
| 193 | TBH, I want to document this: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=262001 | |
| documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc | ||
|---|---|---|
| 193 | The bug refers to Troubleshoot Unconstrained Formatting Pairs | Asciidoctor Docs, which includes edge cases, however I would not have treated the bug as requiring troubleshooting. More simply: from quick reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#ex-unconstrained, I would have known to surround the phrase flavor with pairs of underscores. The subsequent underscore is simply an underscore. | |
Comment Actions
Incidentally, why the Hell did my inline view of my comment disappear before submission?
Phabricator … hmmph :-(
| documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc | ||
|---|---|---|
| 158 | Would suggest adding here something that attempts to explain the terms "constrained" and "unconstrained", with a link to https://docs.asciidoctor.org/asciidoc/latest/text/#formatting-marks-and-pairs For example: AsciiDoctor has a rich set of styles for formatting text, based on surrounding the text to be formatted with a pair of formatting characters. These are known as `formatting pairs`. It is possible to use simplified markup - referred to as `constrained` formatting - if the text to be formatted is surrounded entirely by whitespace or punctuation. Otherwise more verbose markup involving double opening and closing characters - `unconstrained formatting pairs` - will be necessary. The table below gives examples of both. More detail is available in the link:https://docs.asciidoctor.org/asciidoc/latest/text/#formatting-marks-and-pairs[Asciidoc documentation]. {my link syntax may be incorrect, I often don't get it right without checking} | |
| 166 | I suggest "formatting pair" all through this table, now that we have described what they are. So new lines would read, e.g. This is a constrained \*bold* pair This is an unconstrained \**bold\** formatting pair (I assume both leading \**asterisks\** need to be escaped?) | |
| 193 | "To achieve formatting using complex styles which repeat characters which should appear in the formatted text, unconstrained formatting pairs are recommended." | |
| 194 | For example, to obtain the output __flavor___PKGNAMEPREFIX, the syntax would be \__flavor____PKGNAMEPREFIX. | |