From 53ec5f0a05d128e906c5111a62b4e4a0787d82fb Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Wed, 4 Jul 2018 22:11:55 +0200 Subject: [PATCH] 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. --- doc/org-manual.org | 73 ++++++++++++++++++++++++++++------------------ 1 file changed, 45 insertions(+), 28 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index ab504e4cd..74d137dbf 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) - -#+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) + +#+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 + +#+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.