org-mode for package documentation

org-mode for package documentation

[Christopher Dimech]

Dear Compeers,

Some months ago there had been a discussion about using org-mode
to produce package documentation.  Which would allow the use of  
Latex3 (e.g. use of colour, floating images).  

What is the current status for that?

Christopher

Re: org-mode for package documentation

[Philip Kaludercic]

Christopher Dimech <dimech@gmx.com> writes:

> Dear Compeers,
>
> Some months ago there had been a discussion about using org-mode
> to produce package documentation.  Which would allow the use of  
> Latex3 (e.g. use of colour, floating images).

Where/when did this happen?  Could you provide a few pointers?

> What is the current status for that?
>
> Christopher

Re: org-mode for package documentation

[Björn Bidar]

Philip Kaludercic <philipk@posteo.net> writes:

> Christopher Dimech <dimech@gmx.com> writes:
>
>> Dear Compeers,
>>
>> Some months ago there had been a discussion about using org-mode
>> to produce package documentation.  Which would allow the use of  
>> Latex3 (e.g. use of colour, floating images).
>
> Where/when did this happen?  Could you provide a few pointers?

I don't know exactly but when use-package was merged into Emacs there
were discussions if keeping the documentation in org-mode format is
fine.

From what I understood it is possible.

Re: org-mode for package documentation

[Philip Kaludercic]

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Christopher Dimech <dimech@gmx.com> writes:
>>
>>> Dear Compeers,
>>>
>>> Some months ago there had been a discussion about using org-mode
>>> to produce package documentation.  Which would allow the use of  
>>> Latex3 (e.g. use of colour, floating images).
>>
>> Where/when did this happen?  Could you provide a few pointers?
>
> I don't know exactly but when use-package was merged into Emacs there
> were discussions if keeping the documentation in org-mode format is
> fine.
>
> From what I understood it is possible.

Using org-mode to generate TeXinfo manuals is already possible, due to
the ox-texinfo backend, but I haven't been personally that satisfied
with the quality of the output, due to the lack of (easy) support for
the fine distinctions in markup that texinfo provides.  That is why the
use-package documentation had to be translated from org-mode to texinfo,
which was part of the reason the process of merging took so long.

Re: org-mode for package documentation

[David Masterson]

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Christopher Dimech <dimech@gmx.com> writes:
>>
>>> Dear Compeers,
>>>
>>> Some months ago there had been a discussion about using org-mode
>>> to produce package documentation.  Which would allow the use of  
>>> Latex3 (e.g. use of colour, floating images).
>>
>> Where/when did this happen?  Could you provide a few pointers?
>
> I don't know exactly but when use-package was merged into Emacs there
> were discussions if keeping the documentation in org-mode format is
> fine.
>
> From what I understood it is possible.

Org-mode can export to Texinfo/Info.  All that's needed is proper
conventions for writing the document such that it's compatible with
Info).

-- 
David Masterson

Re: org-mode for package documentation

[Payas Relekar]

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Christopher Dimech <dimech@gmx.com> writes:
>>
>>> Dear Compeers,
>>>
>>> Some months ago there had been a discussion about using org-mode
>>> to produce package documentation.  Which would allow the use of
>>> Latex3 (e.g. use of colour, floating images).
>>
>> Where/when did this happen?  Could you provide a few pointers?
>
> I don't know exactly but when use-package was merged into Emacs there
> were discussions if keeping the documentation in org-mode format is
> fine.
>
> From what I understood it is possible.

IIRC, Richard Stallman said he'd be amenable to it, _provided that_ Org
fulfilled all the requisite functionality from Texinfo.

Ihor (org maintainer) was also receptive, but I don't remember if/how
much progress happened towards the goal.

--

Re: org-mode for package documentation

[Ihor Radchenko]

Payas Relekar <relekarpayas@gmail.com> writes:

> IIRC, Richard Stallman said he'd be amenable to it, _provided that_ Org
> fulfilled all the requisite functionality from Texinfo.

Correct. We need to add more flexible markup. The idea was to add
something similar to special blocks, but inline. Currently, ox-texinfo
is approaching the extended markup with macros. See doc/doc-setup.org.

> Ihor (org maintainer) was also receptive, but I don't remember if/how
> much progress happened towards the goal.

We discussed possible syntax of inline custom markup to be added. See
https://orgmode.org/list/87bkqx4jyg.fsf@localhost Someone is to go ahead
and try to implement it. It might be me in future, but I am prioritizing
working on some other new features in Org for now.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: org-mode for package documentation

[Philip Kaludercic]

Ihor Radchenko <yantar92@posteo.net> writes:

> Payas Relekar <relekarpayas@gmail.com> writes:
>
>> IIRC, Richard Stallman said he'd be amenable to it, _provided that_ Org
>> fulfilled all the requisite functionality from Texinfo.
>
> Correct. We need to add more flexible markup. The idea was to add
> something similar to special blocks, but inline. Currently, ox-texinfo
> is approaching the extended markup with macros. See doc/doc-setup.org.
>
>> Ihor (org maintainer) was also receptive, but I don't remember if/how
>> much progress happened towards the goal.
>
> We discussed possible syntax of inline custom markup to be added. See
> https://orgmode.org/list/87bkqx4jyg.fsf@localhost Someone is to go ahead
> and try to implement it. It might be me in future, but I am prioritizing
> working on some other new features in Org for now.

My general question is what advantage this would provide over just using
TeXinfo in the first place, if the required complexity of the markup has
to be the same as for TeXinfo in the first place?

Re: org-mode for package documentation

[Ihor Radchenko]

Philip Kaludercic <philipk@posteo.net> writes:

>> We discussed possible syntax of inline custom markup to be added. See
>> https://orgmode.org/list/87bkqx4jyg.fsf@localhost Someone is to go ahead
>> and try to implement it. It might be me in future, but I am prioritizing
>> working on some other new features in Org for now.
>
> My general question is what advantage this would provide over just using
> TeXinfo in the first place, if the required complexity of the markup has
> to be the same as for TeXinfo in the first place?

Check out the original thread where RMS officially suggested that Org
can be used instead of texinfo.

In short, Org provides much more configurable export output. You can
customize it using Elisp or within Org document itself. You can generate
parts of documentation using output of src blocks. You can fine-tune
specific export output formats using inline export blocks. etc ...

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>