summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2018-07-04 22:11:55 +0200
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2018-07-04 23:35:04 +0200
commit53ec5f0a05d128e906c5111a62b4e4a0787d82fb (patch)
treed67fefa586a3cf0d69d995021be6d310637260b2
parentb3e00f0c53733845fa2577181d81610ae9528230 (diff)
downloadorg-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.org73
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.