From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: org.texi edits, patch attached Date: Mon, 19 Dec 2016 00:39:46 +0100 Message-ID: <87wpew24e5.fsf@nicolasgoaziou.fr> References: <874m3efhfw.fsf@nicolasgoaziou.fr> <87d1hxp4kk.fsf@nicolasgoaziou.fr> <87vavoo4lz.fsf@nicolasgoaziou.fr> <87mvgxoguq.fsf@nicolasgoaziou.fr> <877f81nqpe.fsf@nicolasgoaziou.fr> <87bmx1euca.fsf@nicolasgoaziou.fr> <87k2bgbmol.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:56134) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cIl3X-0003pT-Am for emacs-orgmode@gnu.org; Sun, 18 Dec 2016 18:39:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cIl3S-0001am-45 for emacs-orgmode@gnu.org; Sun, 18 Dec 2016 18:39:51 -0500 Received: from relay4-d.mail.gandi.net ([217.70.183.196]:34727) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cIl3R-0001YC-P5 for emacs-orgmode@gnu.org; Sun, 18 Dec 2016 18:39:46 -0500 In-Reply-To: (Lambda Coder's message of "Wed, 14 Dec 2016 22:45:04 -0800") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Lambda Coder Cc: emacs-orgmode@gnu.org Hello, Lambda Coder 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. T= he > +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 specializ= ed > +libraries from the Emacs packaging system.=20=20 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 setti= ngs. > +The @kbd{C-u} prefix argument preserves options from the previous export, > +including any sub-tree selections as long as buffer contents have not ch= anged > +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 s= tarting > +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 c= ursor > +is not on a heading, Org uses the nearest enclosing header. If the curs= or 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=20 > +@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 t= he > -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=C3=A8res}. > +The default value is @code{:export:}. When a tree is tagged with > +@code{:export:} (@code{org-export-select-tags}), Org selects that tree a= nd > +its sub-trees for export. Org excludes trees with @code{:noexport:} tag= s (see > +below).=20=20 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 exp= ort. > +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 >=20=20 > -You can insert text that will only appear when using @code{ASCII} back-e= nd > -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 ot= her > +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 headli= nes > +@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: >=20=20 > @c @example > @c @kbd{C-2 C-c C-e b} > @c @end example >=20=20 > @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 lis= ts. 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{ +class=3D"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 cha= nges > +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 O= DT > +using a specialized ODT converter process. Its common interface works w= ith > +popular converters to produce formats such as @samp{doc}, or convert a > +document from one format (say @samp{csv}) to another format (say @samp{o= ds} > +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 ima= ges > +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 >=20=20 > @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 a= lso 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, --=20 Nicolas Goaziou