emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* org-mode for package documentation
@ 2023-04-28 18:42 Christopher Dimech
  2023-04-28 21:08 ` Philip Kaludercic
  0 siblings, 1 reply; 9+ messages in thread
From: Christopher Dimech @ 2023-04-28 18:42 UTC (permalink / raw)
  To: Help Emacs Orgmode, Help Gnu Emacs

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



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
  2023-04-28 18:42 Christopher Dimech
@ 2023-04-28 21:08 ` Philip Kaludercic
  2023-05-27 17:18   ` Björn Bidar
  0 siblings, 1 reply; 9+ messages in thread
From: Philip Kaludercic @ 2023-04-28 21:08 UTC (permalink / raw)
  To: Christopher Dimech; +Cc: Help Emacs Orgmode, Help Gnu Emacs

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


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
  2023-04-28 21:08 ` Philip Kaludercic
@ 2023-05-27 17:18   ` Björn Bidar
  2023-05-28 11:08     ` Philip Kaludercic
  2023-06-06 16:49     ` David Masterson
  0 siblings, 2 replies; 9+ messages in thread
From: Björn Bidar @ 2023-05-27 17:18 UTC (permalink / raw)
  To: Philip Kaludercic; +Cc: Christopher Dimech, Help Emacs Orgmode, Help Gnu Emacs

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.


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
  2023-05-27 17:18   ` Björn Bidar
@ 2023-05-28 11:08     ` Philip Kaludercic
  2023-06-06 16:49     ` David Masterson
  1 sibling, 0 replies; 9+ messages in thread
From: Philip Kaludercic @ 2023-05-28 11:08 UTC (permalink / raw)
  To: Björn Bidar; +Cc: Christopher Dimech, Help Emacs Orgmode, Help Gnu Emacs

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.


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
@ 2023-05-28 11:14 Payas Relekar
  2023-05-29  7:54 ` Ihor Radchenko
  0 siblings, 1 reply; 9+ messages in thread
From: Payas Relekar @ 2023-05-28 11:14 UTC (permalink / raw)
  To: Björn Bidar
  Cc: Philip Kaludercic, Christopher Dimech, Help Emacs Orgmode,
	Help Gnu Emacs

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.

--


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
  2023-05-28 11:14 org-mode for package documentation Payas Relekar
@ 2023-05-29  7:54 ` Ihor Radchenko
  2023-05-29  7:55   ` Philip Kaludercic
  0 siblings, 1 reply; 9+ messages in thread
From: Ihor Radchenko @ 2023-05-29  7:54 UTC (permalink / raw)
  To: Payas Relekar
  Cc: Björn Bidar, Philip Kaludercic, Christopher Dimech,
	Help Emacs Orgmode, Help Gnu Emacs

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>


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
  2023-05-29  7:54 ` Ihor Radchenko
@ 2023-05-29  7:55   ` Philip Kaludercic
  2023-05-29  8:26     ` Ihor Radchenko
  0 siblings, 1 reply; 9+ messages in thread
From: Philip Kaludercic @ 2023-05-29  7:55 UTC (permalink / raw)
  To: Ihor Radchenko
  Cc: Payas Relekar, Björn Bidar, Christopher Dimech,
	Help Emacs Orgmode, Help Gnu Emacs

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?


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
  2023-05-29  7:55   ` Philip Kaludercic
@ 2023-05-29  8:26     ` Ihor Radchenko
  0 siblings, 0 replies; 9+ messages in thread
From: Ihor Radchenko @ 2023-05-29  8:26 UTC (permalink / raw)
  To: Philip Kaludercic
  Cc: Payas Relekar, Björn Bidar, Christopher Dimech,
	Help Emacs Orgmode, Help Gnu Emacs

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>


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: org-mode for package documentation
  2023-05-27 17:18   ` Björn Bidar
  2023-05-28 11:08     ` Philip Kaludercic
@ 2023-06-06 16:49     ` David Masterson
  1 sibling, 0 replies; 9+ messages in thread
From: David Masterson @ 2023-06-06 16:49 UTC (permalink / raw)
  To: Björn Bidar
  Cc: Philip Kaludercic, Christopher Dimech, Help Emacs Orgmode,
	Help Gnu Emacs

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


^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2023-06-06 16:50 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-05-28 11:14 org-mode for package documentation Payas Relekar
2023-05-29  7:54 ` Ihor Radchenko
2023-05-29  7:55   ` Philip Kaludercic
2023-05-29  8:26     ` Ihor Radchenko
  -- strict thread matches above, loose matches on Subject: below --
2023-04-28 18:42 Christopher Dimech
2023-04-28 21:08 ` Philip Kaludercic
2023-05-27 17:18   ` Björn Bidar
2023-05-28 11:08     ` Philip Kaludercic
2023-06-06 16:49     ` David Masterson

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).