Re: org.texi edits, patch attached

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> I have more. I've just finished the Exporting chapter. See the attached
> patch file against current maint branch.

Thank you!

Usual comments and questions follow.

> +Org has export facilities for printing, format conversions, and general
> +sharing of Org documents with the outside world.  Org export supports
> +pretty-printing, web publishing, slide shows, and quick exports of lists and
> +tables to many foreign formats while retaining as much structure
> +(@pxref{Document structure}) and markup (@pxref{Markup}) as possible.  The
> +many features of Org exports are constantly being improved and expanded and
> +they are all explained in this chapter.

I would remove "are constantly being improved and expanded and they"

> +@noindent Org also uses additional libraries located in @code{contrib/}
> +directory (@pxref{Installation}).  Users can install even more specialized
> +libraries from the Emacs packaging system.  

Nitpick: libraries from the Emacs packaging system may not be "more
specialized", but just different.

What about dropping "specialized"?

> +Invokes the export dispatcher interface.  The options show default settings.
> +The @kbd{C-u} prefix argument preserves options from the previous export,
> +including any sub-tree selections as long as buffer contents have not changed
> +since the last export.

The last part of the sentence above is incorrect. Buffer contents may
have changed between two exports. Otherwise, there is not much interest
in exporting the same thing twice, even with a shortcut.

> -Toggle subtree export.  The top heading becomes the document title.
> +Toggle sub-tree export.  When turned on, Org exports only the sub-tree starting
> +from the cursor position at the time the export dispatcher was invoked.  Org
> +uses the top heading of this sub-tree as the document's title.  If the cursor
> +is not on a heading, Org uses the nearest enclosing header.  If the cursor is
> +in the document preamble, Org signals an error and aborts export.

I wonder if the last sentence isn't too technical for a manual.
Shouldn't we leave that for a docstring?

> +Options set through properties
> +(@pxref{Properties and columns}) apply to that specific heading and its
> +subheadings.  Properties are inherited in the hierarchy, and, in case of
> +overlap, options set at the specific level override those set at the more
> +general and global levels.

This is not correct. Options set through properties apply only when
doing a sub-tree export. Besides, even in this case, properties are not
necessarily inherited. It depens on `org-use-property-inheritance'.

> -A date or a time-stamp@footnote{The variable
> -@code{org-export-date-timestamp-format} defines how this time-stamp will be
> -exported.}.
> +A date or a time-stamp@footnote{The export format is specified in 
> +@code{org-export-date-timestamp-format}.}.

`org-export-date-timestamp-format' has an effect only when DATE is
a time-stamp. It isn't obvious by reading the above.

>  @item EMAIL
>  @cindex #+EMAIL
> @@ -10436,46 +10465,47 @@ The email address (@code{user-mail-address}).
>  @item LANGUAGE
>  @cindex #+LANGUAGE
>  @vindex org-export-default-language
> -The language used for translating some strings
> -(@code{org-export-default-language}).  E.g., @samp{#+LANGUAGE: fr} will tell
> -Org to translate @emph{File} (english) into @emph{Fichier} (french) in the
> -clocktable.
> +Language to use for translating certain strings
> +(@code{org-export-default-language}).  With @samp{#+LANGUAGE: fr}, for
> +example for the clocktable, Org translates the English @emph{File} to the
> +French @emph{Fichier}.

The example needs to be changed (so did the old one).
`org-export-default-language' has no effect on the Clock Table.
I suggest to replace it with a real example, e.g.

  With @samp{#+LANGUAGE: fr}, for example, Org translates @emph{Table of
  contents} to the French @emph{Table des matières}.

> +The default value is @code{:export:}.  When a tree is tagged with
> +@code{:export:} (@code{org-export-select-tags}), Org selects that tree and
> +its sub-trees for export.  Org excludes trees with @code{:noexport:} tags (see
> +below).  

Usual nitpick:

  tags---see below.

> -Toggle inclusion of drawers, or list drawers to include
> +Toggle inclusion of drawers, or list-drawers to include

Is this a typo? `org-export-with-drawers' can contain a list of drawers
to include (or not).

> +``Planning information'' comes from lines containing any combination of these
> +cookies: @code{SCHEDULED:}, @code{DEADLINE:}, or @code{CLOSED:}.

and located right after the headline.

> +Org converts the first three outline levels into headlines for ASCII export.
> +The remaining levels are turned into lists.  To change this cut-off point
> +where levels become lists, (@pxref{Export settings}).

You should remove the parenthesis above.

>  @subheading Quoting ASCII text
>  
> -You can insert text that will only appear when using @code{ASCII} back-end
> -with the following constructs:
> +To insert text within the Org file by the @code{ASCII} back-end, use one the
> +following constructs, inline, keyword, or export block:

For consistency (with, e.g., HTML or some others "ASCII" in the manual),

  @code{ASCII} -> ASCII

>  #+BEGIN_EXPORT ascii
> -All lines in this block will appear only when using this back-end.
> +Org exports text in this block only when using @code{ASCII} back-end.

Ditto.

> +@code{ASCII} back-end recognizes only one attribute, @code{:width},
> which

Ditto.

> +Besides @code{#+BEGIN_CENTER} blocks (@pxref{Paragraphs}),
> @code{ASCII}

Ditto.

> +Org uses @emph{Beamer} export to convert an Org file tree structure into a
> +high-quality interactive slides for presentations.  @emph{Beamer} is a
> +@LaTeX{} document class for creating presentations in PDF, HTML, qand other
> +popular display formats.

Typo: qand > and

> +Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
> +it recognizes other @LaTeX{} specific syntax (for example, @samp{#+LATEX:} or
> +@samp{#+ATTR_LATEX:}).  See @ref{@LaTeX{} export} for details.

Last sentence should be

  @xref{@LaTeX{} export}, for details.

The comma is mandatory.

> +@example
> +#+ATTR_BEAMER: :options [Lagrange]
> +Let $G$ be a finite group, and let $H$ be
> +a subgroup of $G$.  Then the order of $H$ divides the order of $G$.
> +@end example

The example above does nothing useful, does it? :options do not apply to
paragraphs AFAIK.

> +Org mode contains an HTML exporter with extensive HTML formatting (XHTML 1.0
> +strict), in ways similar to John Gruber's @emph{markdown} language, but with
> +additional support for tables.

  HTML formatting---XHTML 1.0 strict.

I'm not sure comparing HTML back-end to markdown is realistic nowadays.
Both are very different. We may drop the last part of the sentence.

> +@c Org's HTML export converts the first three outline levels into headlines
> +@c for HTML export.  The remaining levels are turned into itemized lists.  To
> +@c change this globally for the cut-off point where levels become lists,
> +@c (@pxref{Export settings}).  To change just for this document for now,
> +@c specify a numeric prefix argument, such as:
>  
>  @c @example
>  @c @kbd{C-2 C-c C-e b}
>  @c @end example
>  
>  @c @noindent
> -@c creates two levels of headings and does the rest as items.
> +@c creates the first two levels as headings and the rest as itemized lists.

What about removing the comments? (@c)

> +Specify the document type, for example: HTML5, (@code{org-html-doctype}).

I would remove the last comma:

  for example: HTML5 (@code{org-html-doctype}).

> +Options for MathJax (@code{org-html-mathjax-options}).  MathJax is used to
> +typeset @LaTeX{} math in HTML documents.  @ref{Math formatting in HTML
> +export} has an example.

  @xref{Math formatting in HTML export}, for an example.

> -Arbitrary lines appended to the end of the header of the document
> -(@code{org-html-head-extra}).
> +More arbitrary lines for appending to the HTML document's head.
> +(@code{org-html-head-extraq}).

Typo: extraq -> extra

Also, I would remove the penultimate period:

  ... HTML document's head (@code{org-html-head-extra}).
> +When special blocks do not have a corresponding HTML5 element (see
> +@code{org-html-html5-elements}), the HTML exporter reverts to standard
> +translation.  For example, @code{#+BEGIN_lederhosen} exports to @samp{<div
> +class="lederhosen">}.

  HTML5 element---see @code{org-html-html5-elements}---the HTML exporter...

> +The HTML export back-end transforms Org's internal links (@pxref{Internal
> +links}) to equivalent HTML links in the output.  The back-end similarly
> +handles Org's automatic links created by radio targets (@pxref{Radio
> +targets}) similarly.  For Org links to external files, the back-end
> +transforms the links to @i{relative} paths.

@i{relative} -> @emph{relative}

> +For Org links to other @file{.org} files, the back-end automatically changes
> +the file extension to @file{.html} and makes file paths relative.  If the
> +@file{.org} files have an equivalent @file{.html} version at the same
> +location, then the converted links should work without any further manual
> +intervention.  However, to disable this automatic path translation, set
> +@code{org-html-link-org-files-as-html} to @code{nil}.  When disabled, the
> +HTML export back-end substitutes the @samp{id:}-based links in the HTML
> +output.  For more about linking files when publishing to a directory, see
> +@ref{Publishing links}.

  ... to a directory, @pxref{Publishing links}.

> -You could use @code{http} addresses just as well.
> +The HTTP export back-end copies the @code{http} links from the Org file as
> +is.

There is no such thing as a "HTTP" export back-end? What do you mean here?

>  @c FIXME: More about header and footer styles
> -@c FIXME: Talk about links and targets.
> +@c FIXME: Talk about lfinks and targets.

Typo: lfinks -> links

>  #+BEGIN_SRC emacs-lisp
> -  (defun Fib (n)                          ; Count rabbits.
> +  (defun Fib (n)
>      (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
>  #+END_SRC

You ruined the joke :)

> +The ODT export back-end can produce documents in other formats besides ODT
> +using a specialized ODT converter process.  Its common interface works with
> +popular converters to produce formats such as @samp{doc}, or convert a
> +document from one format (say @samp{csv}) to another format (say @samp{ods}
> +or @samp{xls}).

  from one format, say @samp{csv}, to another format, say @samp{ods}.

I would drop the "xls" part.

> +The ODT export back-end starts with the size dimensions (in centimeters) of

  size dimensions---in centimeters--of

> +To modify the category component of the caption, customize the option
> +@code{org-odt-category-map-alist}.  For example, to tag all embedded images
> +with the string @samp{Illustration} (instead of the default @samp{Figure})
> +use the following setting:

  ... the string @samp{Illustration}---instead of the default
  @samp{Figure}---use the following setting :

>  @lisp
>  (setq org-odt-category-map-alist
>        (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))

There is a quote missing at the beginning of the second line.

> +The ODT export back-end can read one-liner options on line with @code{#+ODT:}
> +in the Org file.

I cannot parse this sentence. Would it need clarifications?

>  @example
> -#+attr_texinfo: :options org-org-export-to-org ...
> +#+attr_texinfo: :options opt1 opt2 opt3 ...
>  #+begin_defun
>  A somewhat obsessive function.
>  #+end_defun
>  @end example

You also ruined the joke :) You need to replace the contents of the
defun, which do not make sense anymore.

Also, #+begin_defun expects a function name, not arguments.

>  @noindent
> -becomes
> +exports to
>  
>  @example
> -@@defun org-org-export-to-org ...
> +@@defun opt1 opt2 opt3 ...
>  A somewhat obsessive function.
>  @@end defun
>  @end example

Ditto.

> +The iCalendar export back-end can also incorporate TODO entries based on the
> +configuration of the @code{org-icalendar-include-todo} variable.  The
> +back-end exports plain timestamps as VEVENT, TODO items as VTODO@, and also

  VTODO@, -> VTODO,

> -language in the block.  @xref{Languages}, for identifiers of supported
> +language in the block.  @xref{Languages} for identifiers of supported

Please revert this chunck, a comma (or full stop) is necessary after
"@xref".


Could you send an updated patch?


Regards,

-- 
Nicolas Goaziou