diff options
author | Nicolas Goaziou <mail@nicolasgoaziou.fr> | 2018-07-04 22:11:55 +0200 |
---|---|---|
committer | Nicolas Goaziou <mail@nicolasgoaziou.fr> | 2018-07-04 23:35:04 +0200 |
commit | 53ec5f0a05d128e906c5111a62b4e4a0787d82fb (patch) | |
tree | d67fefa586a3cf0d69d995021be6d310637260b2 | |
parent | b3e00f0c53733845fa2577181d81610ae9528230 (diff) | |
download | org-mode-53ec5f0a05d128e906c5111a62b4e4a0787d82fb.tar.gz |
org-manual: Improve and relocate linter documentation
* doc/org-manual.org (Org Syntax): Move to "Miscellaneous". Expound
documentation about how to use the linter.
The syntax happens too early in the manual, before most elements are
even described.
-rw-r--r-- | doc/org-manual.org | 73 |
1 files changed, 45 insertions, 28 deletions
diff --git a/doc/org-manual.org b/doc/org-manual.org index ab504e4..74d137d 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -1370,34 +1370,6 @@ The following command handles footnotes: reference, and you can use the usual commands to follow these links. -** Org Syntax -:PROPERTIES: -:DESCRIPTION: Formal description of Org's syntax. -:END: - -A reference document providing a formal description of Org's syntax is -available as [[https://orgmode.org/worg/dev/org-syntax.html][a draft on Worg]], written and maintained by Nicolas -Goaziou. It defines Org's core internal concepts such as =headlines=, -=sections=, =affiliated keywords=, =(greater) elements= and =objects=. -Each part of an Org file falls into one of the categories above. - -To explore the abstract structure of an Org buffer, run this in -a buffer: - -: M-: (org-element-parse-buffer) <RET> - -#+texinfo: @noindent -It outputs a list containing the buffer's content represented as an -abstract structure. The export engine relies on the information -stored in this list. Most interactive commands---e.g., for structure -editing---also rely on the syntactic meaning of the surrounding -context. - -#+cindex: syntax checker -#+cindex: linter -#+findex: org-lint -You can check syntax in your documents using ~org-lint~ command. - * Tables :PROPERTIES: :DESCRIPTION: Pure magic for quick formatting. @@ -19229,6 +19201,51 @@ specifying the respective key as property =CRYPTKEY=, e.g.: Excluding the =crypt= tag from inheritance prevents already encrypted text from being encrypted again. +** Org Syntax +:PROPERTIES: +:DESCRIPTION: Formal description of Org's syntax. +:END: + +A reference document providing a formal description of Org's syntax is +available as [[https://orgmode.org/worg/dev/org-syntax.html][a draft on Worg]], written and maintained by Nicolas +Goaziou. It defines Org's core internal concepts such as "headlines", +"sections", "affiliated keywords", "(greater) elements" and "objects". +Each part of an Org document belongs to one of the previous +categories. + +To explore the abstract structure of an Org buffer, run this in +a buffer: + +: M-: (org-element-parse-buffer) <RET> + +#+texinfo: @noindent +It outputs a list containing the buffer's content represented as an +abstract structure. The export engine relies on the information +stored in this list. Most interactive commands---e.g., for structure +editing---also rely on the syntactic meaning of the surrounding +context. + +#+cindex: syntax checker +#+cindex: linter +#+findex: org-lint +You can probe the syntax of your documents with the command + +: M-x org-lint <RET> + +#+texinfo: @noindent +It runs a number of checks to find common mistakes. It then displays +their location in a dedicated buffer, along with a description and +a "trust level", since false-positive are possible. From there, you +can operate on the reports with the following keys: + +#+attr_texinfo: :columns 0.22 0.78 +| {{{kbd(C-j)}}}, {{{kbd(TAB)}}} | Display the offending line | +| {{{kbd(RET)}}} | Move point to the offending line | +| {{{kbd(g)}}} | Check the document again | +| {{{kbd(h)}}} | Hide all reports from the same checker | +| {{{kbd(i)}}} | Also remove them from all subsequent checks | +| {{{kbd(S)}}} | Sort reports by the column at point | + * Hacking :PROPERTIES: :DESCRIPTION: How to hack your way around. |