Re: examples for org-manual

Re: examples for org-manual

[Vincent Breton]

Hi,


Emacs and Emacs Org documentation, and lot of others GNU products use
Texinfo to generate their own  documentation to different formats.
Unlucky, they are just the HTML version on
https://www.gnu.org/software/emacs/manual/org.html and It is not for
lack of having written the 22 november 2021 a message about org
documentation... on this list.

I remember you can access to a PDF version of Org I published on
http://www.presentiel.com/org/org.pdf.
and another one more short: http://www.presentiel.com/org/orgguide.pdf.

In my opinion, the trouble with just  a Wiki is not the most appropriate
for printed version and in a Wiki or others CMS, some pages are short
and others long without page number so it's more difficult to appreciate
the length of the document and the time to study it. They are also
others troubles with Web pages about security or about private life when
you explore a web site...

That why I encourage to publish documentation with different formats,
more particularly when the doc is written for Texinfo tool who make all
the work easily.

In my experience, the best thing to do is to start to write a draft
using plain text. If you prefer, you can also use directly a CMS to
generate HTML: only HTML where it's easy to copy and past text but
please in all cases  use a very simple CSS if you use it. In my
opinion,that is a good idea to use a common tool as git to publish and
update your work but don't forget to inform.

If your content is good and clear, it will be interesting to upgrade it
to a beautiful book: that's another work very hard for some people and
very simple for others: generally the last one use (La)TeX years after
years.

I'm sure, some people will play the game with accepting to send and
publish for free interesting examples for Org. On this forum, I'm sure
you will find too lot of tips and tricks.

In my opininon the big difference between a manual and a book about Gnu
products are layout, illustrations and copyrights.

I hope to read soon your first writings  about some Org examples before
I provide you a PDF version made with LaTeX and without change of text.

Best regards

On 02/12/2021 03:58, brownexitus wrote:

> Hi Vincent, t
>
> I hear what you say, but isn't more efficient to have something like the emacs wiki etc? or even links to other sites that explain it that way?
>
> If the manual is available somewhere on git (I'm new to this whole thing), perhaps I can try to offer changes that will go in there. I don't know that that's possible though.
>
> creating a PDF and contributing to it like that is similar to writing a book, which is not a bad idea in itself, but it's not going to lift off the ground as easy as just contributing to the manual...? What do you think.
>
>> Hi,
>>
>> In my opinion, lot of manuals don't have enough examples.
>>
>> One way to solve this would be to create a list of examples in another
>>
>> document with references to the org documentation in PDF format (page
>>
>> numbers, relevant sections...). This would not change anything in the
>>
>> original documentation and would make it easier to understand or to
>>
>> identify possible obscure and incomplete aspects.
>>
>> Once the list of examples is sufficiently complete and validated, it
>>
>> could be attached to the original documentation with for example at
>>
>> least a paragraph and a link to consult this compilation of examples
>>
>> playing the role of a large appendix, or even links to the examples
>>
>> document in the text for the most interesting examples.
>>
>> It's a big job but if enough people would contribute according to their
>>
>> possibilities and time, we would have much more than a simple book of
>>
>> examples.
>>
>> I hope it will be useful.
>>
>> On 01/12/2021 05:09, brownexitus via General discussions about Org-mode.
>>
>> wrote:
>>
>>> The org-manual could use more practical examples, in my opinion.
>>>
>>> How does one submit suggestions/edits?
>

Re: examples for org-manual

[Kaushal Modi]

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

On Thu, Dec 2, 2021, 8:08 AM Vincent Breton <emacs-orgmode@presentiel.fr>
wrote:

> Hi,
>
>
> Emacs and Emacs Org documentation, and lot of others GNU products use
> Texinfo to generate their own  documentation to different formats.


The Org mode documentation switched to Org format few years back:
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/doc/org-manual.org

Yes, originally, it was in Texinfo.

[-- Attachment #2: Type: text/html, Size: 912 bytes --]

Re: examples for org-manual

[Vincent Breton]

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

Thank you very much for your message and the link.

Does Org format produce the .texi format for TexInfo ?  I found the
official reply here: https://orgmode.org/manual/Texinfo-export-commands.html

Org format seams to be a top layer format to produce others formats.
That seams to be a good reason to use Org format but in another way and
in my opinion, just providing HTML format on the documentation web page
for Gnu Org is a regression. Most of GNU documentations for others
products provide an access to different formats on the same page. HTML
is useful but it can't replace PDF format.


On 02/12/2021 15:53, Kaushal Modi wrote:
> On Thu, Dec 2, 2021, 8:08 AM Vincent Breton
> <emacs-orgmode@presentiel.fr <mailto:emacs-orgmode@presentiel.fr>> wrote:
>
>     Hi,
>
>
>     Emacs and Emacs Org documentation, and lot of others GNU products use
>     Texinfo to generate their own  documentation to different formats.
>
>
> The Org mode documentation switched to Org format few years
> back: https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/doc/org-manual.org
> <https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/doc/org-manual.org>
>
> Yes, originally, it was in Texinfo. 

[-- Attachment #2: Type: text/html, Size: 2473 bytes --]

examples for org-manual

[brownexitus via General discussions about Org-mode.]

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

The org-manual could use more practical examples, in my opinion.
How does one submit suggestions/edits?

[-- Attachment #2: Type: text/html, Size: 127 bytes --]

Re: examples for org-manual

[Ihor Radchenko]

brownexitus via "General discussions about Org-mode."
<emacs-orgmode@gnu.org> writes:

> The org-manual could use more practical examples, in my opinion.
> How does one submit suggestions/edits?

Thanks for the interest in improving the manual!
The contribution to manual are done same way as any other contribution -
you need to send patches to this mailing list. If the maintainers agree
with the patch, they will apply it on your behalf. See
https://orgmode.org/worg/org-contribute.html for details.

The source file for the manual is located in the doc/org-manual.org
inside the Org mode repository.

If you just want to give suggestions, an email to this list will do.
Though patches are always more welcome because they take less time on
the maintainer side.

Looking forward for you future contributions.

Best regards,
Ihor