Re: examples for org-manual

[Vincent Breton <emacs-orgmode@presentiel.fr>]

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?
>