Documentation fix

Documentation fix

[Robert Klein]

Hi,

there are two typos which causes compile to fail.  Patch below.

PS: Probably there should be a comma after the “example”.  Sorry, my
English not so good is...

Best regards
Robert





From 355901f48b9b81e9d5509f2df66e4f25eb23adae Mon Sep 17 00:00:00 2001
From: Robert Klein <roklein@roklein.de>
Date: Mon, 15 May 2017 08:31:19 +0200
Subject: [PATCH] Fix typos in Documentation

---
 doc/org.texi | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index d233001..d8173e7 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11367,8 +11367,8 @@ The URL for the up link of exported HTML pages
(@code{org-html-link-up}). @cindex #+HTML_MATHJAX
 @vindex org-html-mathjax-options
 Options for MathJax (@code{org-html-mathjax-options}).  MathJax is
used to -typeset @LaTeX{} math in HTML documents.  @xref{Math
formatting in HTML -export} for an example.
+typeset @LaTeX{} math in HTML documents.  For an example @pxref{Math
+formatting in HTML export}. 
 
 @item HTML_HEAD
 @cindex #+HTML_HEAD
@@ -12198,7 +12198,7 @@ environments.  @code{:spread} has no effect if
@code{:width} is not set. @vindex org-latex-tables-booktabs
 @vindex org-latex-tables-centered
 All three commands are toggles.  @code{:booktabs} brings in modern
-typesetting enhancements to regular tables.  The @code {booktabs}
package has +typesetting enhancements to regular tables.  The
@code{booktabs} package has to be loaded through
@code{org-latex-packages-alist}.  @code{:center} is for centering the
table.  @code{:rmlines} removes all but the very first horizontal line
made of ASCII characters from "table.el" tables only.
-- 
2.6.6

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Robert Klein <roklein@roklein.de> writes:

> there are two typos which causes compile to fail.  Patch below.

Thank you.

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

I don't get this one. It looks valid Texinfo to me. Also, "make info"
doesn't return any error here.

> -typesetting enhancements to regular tables.  The @code {booktabs}
> package has +typesetting enhancements to regular tables.  The
> @code{booktabs} package has to be loaded through
> @code{org-latex-packages-alist}.  @code{:center} is for centering the
> table.  @code{:rmlines} removes all but the very first horizontal line
> made of ASCII characters from "table.el" tables only.

Fixed.

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Robert Klein]

Hallo,

On Mon, 15 May 2017 08:42:42 +0200
Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> Hello,
> 
> Robert Klein <roklein@roklein.de> writes:
> 
> > there are two typos which causes compile to fail.  Patch below.
> 
> Thank you.
> 
> >  Options for MathJax (@code{org-html-mathjax-options}).  MathJax is
> > used to -typeset @LaTeX{} math in HTML documents.  @xref{Math
> > formatting in HTML -export} for an example.
> > +typeset @LaTeX{} math in HTML documents.  For an example
> > @pxref{Math +formatting in HTML export}.
> 
> I don't get this one. It looks valid Texinfo to me. Also, "make info"
> doesn't return any error here.

Ahh, well, on second look it only was a warning:

org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.

Best regards
Robert

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Robert Klein <roklein@roklein.de> writes:

> Ahh, well, on second look it only was a warning:
>
> org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.

Oddly, I don't get this warning when using "make info". Anyway, I added
the missing comma. Thank you.

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Colin Baxter]

>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    Nicolas> Hello, Robert Klein <roklein@roklein.de> writes:

    >> Ahh, well, on second look it only was a warning:
    >> 
    >> org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.

    Nicolas> Oddly, I don't get this warning when using "make
    Nicolas> info". Anyway, I added the missing comma. Thank you.

    Nicolas> Regards,

    Nicolas> -- Nicolas Goaziou


It's depends on your version of makeinfo. For example with makeinfo (GNU
texinfo) 4.13, there are no warnings; however, with texi2any (GNU
texinfo) 6.0, as well as the above `.' or `,' warning, there are
multiple `@table has text but no @item' warnings. The docs still make ok, though.

Best wishes,
Colin.

-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Colin Baxter <m43cap@yandex.com> writes:

>>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>     Nicolas> Hello, Robert Klein <roklein@roklein.de> writes:
>
>     >> Ahh, well, on second look it only was a warning:
>     >> 
>     >> org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.
>
>     Nicolas> Oddly, I don't get this warning when using "make
>     Nicolas> info". Anyway, I added the missing comma. Thank you.
>
>     Nicolas> Regards,
>
>     Nicolas> -- Nicolas Goaziou
>
>
> It's depends on your version of makeinfo. For example with makeinfo (GNU
> texinfo) 4.13, there are no warnings; however, with texi2any (GNU
> texinfo) 6.0, as well as the above `.' or `,' warning, there are
> multiple `@table has text but no @item' warnings. The docs still make
> ok, though.

I see, thanks. Could you send the warnings, or better, a patch, so as to
fix them?

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Colin Baxter]

[-- Attachment #1: Type: text/plain, Size: 839 bytes --]

Dear Nicolas,

>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    Nicolas> I see, thanks. Could you send the warnings, or better, a
    Nicolas> patch, so as to fix them?

    Nicolas> Regards,

    Nicolas> -- Nicolas Goaziou


I have attached the warnings when making the documentation using
texi2any (GNU texinfo) 6.0, and a patch for the two '@itemx should not
begin @table' warnings. I am no expert on makeinfo and I just removed
the 'x' from 'itemx', so the patch is trivial. 

I'm not having any luck with the multiple warning: '@table has text but
no @item' warnings. They don't make much sense to me.

Since the docs make satisfactorily with the warnings, perhaps a note in
the documentation might suffice, to the effect that later versions of
texinfo may produce ignorable  warnings.

Best wishes,

Colin.


[-- Attachment #2: /home/redknight/git/org-mode/warnings.txt --]
[-- Type: message/external-body, Size: 101 bytes --]

[-- Attachment #3: /home/redknight/git/org-mode/itemx.patch --]
[-- Type: message/external-body, Size: 102 bytes --]

[-- Attachment #4: Type: text/plain, Size: 110 bytes --]



-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Colin Baxter <m43cap@yandex.com> writes:

> I have attached the warnings when making the documentation using
> texi2any (GNU texinfo) 6.0, and a patch for the two '@itemx should not
> begin @table' warnings. I am no expert on makeinfo and I just removed
> the 'x' from 'itemx', so the patch is trivial. 
>
> I'm not having any luck with the multiple warning: '@table has text but
> no @item' warnings. They don't make much sense to me.
>
> Since the docs make satisfactorily with the warnings, perhaps a note in
> the documentation might suffice, to the effect that later versions of
> texinfo may produce ignorable  warnings.

I'm unable to open the document you sent. I looks like they are not
properly attached to the mail. Could you send them again?

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: Documentation fix

[Colin Baxter]

Dear Nicolas,

>>>>> "NG" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    NG> Hello, Colin Baxter <m43cap@yandex.com> writes:

    >> I have attached the warnings when making the documentation using
    >> texi2any (GNU texinfo) 6.0, and a patch for the two '@itemx
    >> should not begin @table' warnings. I am no expert on makeinfo and
    >> I just removed the 'x' from 'itemx', so the patch is trivial.
    >> 
    >> I'm not having any luck with the multiple warning: '@table has
    >> text but no @item' warnings. They don't make much sense to me.
    >> 
    >> Since the docs make satisfactorily with the warnings, perhaps a
    >> note in the documentation might suffice, to the effect that later
    >> versions of texinfo may produce ignorable warnings.

    NG> I'm unable to open the document you sent. I looks like they are
    NG> not properly attached to the mail. Could you send them again?

    NG> Regards,

    NG> -- Nicolas Goaziou 0x80A93738

Sorry about my previous email.

I've appended (inline) the warnings associated with the documentation output
of 'make all', removing extraneous output.

---- Begin --------
org-version: 9.0.7 (release_9.0.7-478-g30ceb5)
makeinfo --no-split org.texi -o org
makeinfo --html --number-sections --no-split -o org.html org.texi
texi2pdf --batch --clean --expand org.texi
-:1267: warning: @itemx should not begin @table
-:1345: warning: @table has text but no @item
-:1370: warning: @table has text but no @item
-:1416: warning: @table has text but no @item
-:1558: warning: @table has text but no @item
-:1701: warning: @table has text but no @item
-:2837: warning: @table has text but no @item
-:2894: warning: @table has text but no @item
-:3146: warning: @table has text but no @item
-:4796: warning: @table has text but no @item
-:4933: warning: @table has text but no @item
-:5223: warning: @table has text but no @item
-:5454: warning: @table has text but no @item
-:5808: warning: @table has text but no @item
-:6177: warning: @table has text but no @item
-:6308: warning: @table has text but no @item
-:6485: warning: @table has text but no @item
-:6831: warning: @table has text but no @item
-:6891: warning: @table has text but no @item
-:6910: warning: @table has text but no @item
-:6994: warning: @table has text but no @item
-:7402: warning: @table has text but no @item
-:7590: warning: @table has text but no @item
-:7819: warning: @itemx should not begin @table
-:7838: warning: @table has text but no @item
-:7854: warning: @table has text but no @item
-:7949: warning: @table has text but no @item
-:8107: warning: @table has text but no @item
-:8173: warning: @table has text but no @item
-:8342: warning: @table has text but no @item
-:8726: warning: @table has text but no @item
-:9499: warning: @table has text but no @item
-:9569: warning: @table has text but no @item
-:9636: warning: @table has text but no @item
-:10342: warning: @table has text but no @item
-:10919: warning: @table has text but no @item
-:11233: warning: @table has text but no @item
-:11304: warning: @table has text but no @item
-:12533: warning: @table has text but no @item
-:13462: warning: @table has text but no @item
-:13881: warning: @table has text but no @item
-:14782: warning: @table has text but no @item
-:17653: warning: @table has text but no @item
This is pdfTeX, Version 3.1415926-2.5-1.40.14 (TeX Live 2013)
 restricted \write18 enabled.
entering extended mode
---------- Cut -----

The 'make all' process continues satisfactorily to its conclusion.

Deleting the 'x' from 'itemx' in org.texi at the lines corresponding to the
warnings '@itemx should not begin @table', that is, at lines 1267, 7819, 10342,
removes those warnings. That's all the patch did.

Best wishes,

Colin.

-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Colin Baxter <m43cap@yandex.com> writes:

> I've appended (inline) the warnings associated with the documentation output
> of 'make all', removing extraneous output.
>
> ---- Begin --------
> org-version: 9.0.7 (release_9.0.7-478-g30ceb5)
> makeinfo --no-split org.texi -o org
> makeinfo --html --number-sections --no-split -o org.html org.texi
> texi2pdf --batch --clean --expand org.texi
> -:1267: warning: @itemx should not begin @table
> -:1345: warning: @table has text but no @item

[...]

>
> The 'make all' process continues satisfactorily to its conclusion.

These are innocuous warnings.  

> Deleting the 'x' from 'itemx' in org.texi at the lines corresponding to the
> warnings '@itemx should not begin @table', that is, at lines 1267, 7819, 10342,
> removes those warnings. That's all the patch did.

This would be wrong. The @orgcmd macro above already introduces @item,
so the second one really needs to be @itemx.

One solution would be to replace the @itemx ... with @xorgkey, @xorgcmd,
or @xorgcmdnki depending on the needs. But then, it would fall-back to
the other warning, i.e., a @table without any @item (all are
@orgsomething macros).

I'm no Texinfo expert, so I'm not sure what is the best way to handle
this. Maybe also create a special macro that would create a table. It
sounds convoluted, though.

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Colin Baxter]

Dear Nicolas,

>>>>> "NG" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    NG> Hello, Colin Baxter <m43cap@yandex.com> writes:

    >> I've appended (inline) the warnings associated with the
    >> documentation output of 'make all', removing extraneous output.
    >> 
    >> ---- Begin -------- org-version: 9.0.7
    >> (release_9.0.7-478-g30ceb5) makeinfo --no-split org.texi -o org
    >> makeinfo --html --number-sections --no-split -o org.html org.texi
    >> texi2pdf --batch --clean --expand org.texi -:1267: warning:
    >> @itemx should not begin @table -:1345: warning: @table has text
    >> but no @item

    NG> [...]

    >> 
    >> The 'make all' process continues satisfactorily to its
    >> conclusion.

    NG> These are innocuous warnings.

    >> Deleting the 'x' from 'itemx' in org.texi at the lines
    >> corresponding to the warnings '@itemx should not begin @table',
    >> that is, at lines 1267, 7819, 10342, removes those
    >> warnings. That's all the patch did.

    NG> This would be wrong. The @orgcmd macro above already introduces
    NG> @item, so the second one really needs to be @itemx.

Yes, I see that.

    NG> One solution would be to replace the @itemx ... with @xorgkey,
    NG> @xorgcmd, or @xorgcmdnki depending on the needs. But then, it
    NG> would fall-back to the other warning, i.e., a @table without any
    NG> @item (all are @orgsomething macros).

    NG> I'm no Texinfo expert, so I'm not sure what is the best way to
    NG> handle this. Maybe also create a special macro that would create
    NG> a table. It sounds convoluted, though.

I'll look at this more carefully and see what I can do - if anything. It
will have to wait until I have the time, though.

Best wishes,

Colin.

-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8