emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Merging ox-texinfo+ into ox-texinfo
@ 2021-11-09 18:01 Jonas Bernoulli
  2021-11-19 12:46 ` Nicolas Goaziou
  0 siblings, 1 reply; 5+ messages in thread
From: Jonas Bernoulli @ 2021-11-09 18:01 UTC (permalink / raw)
  To: emacs-orgmode

Hello,

In the olden days before Org's own manual was written using an org-mode
file, I started doing just that for Magit.  Because ox-texinfo.el wasn't
quite there yet I wrote an extension, ox-texinfo+.el, to fill in the
gaps.  Since then I have written seven more manuals that use my
extension.

I recently talked to Bastien about this and he encouraged to bring up
the possibility of merging ox-texinfo+.el into ox-texinfo.el.

ox-texinfo+ (https://github.com/tarsius/ox-texinfo-plus) has several
features but the one I would like to talk about now is the following.

[If you want to look at the other features now, then please use the
 "next" branch as I am in the process of trimming some of them down
 or even removing them completely.  The main feature is the same in
 the "master" and "next" branches.]

   Create `@deffn` and similar definition items by writing list
   items in Org that look similar to what they will look like in
   Info.  To enable this, add:

   #+TEXINFO_DEFFN: t

   to your Org file.  After doing that, you can create definition
   items like so:

   - Command: magit-section-show

     Show the body of the current section.

   - Function: magit-git-exit-code &rest args
   - Macro: magit-insert-section &rest args
   - Variable: magit-display-buffer-noselect
   - User Option: magit-display-buffer-function
   - Key: q, magit-mode-bury-buffer

I propose that we add this as an optional feature to ox-texinfo.el
itself.

IMO the biggest advantage of this style is that it leads to a prettier
org file, which is suitable for direct consumption by end-users.  It is
also easier to write in this style by package authors who might not want
to fully familiarize themselves with all the peculiarities of writing an
org file intended for export to texinfo.

It is possible to mix the two styles; you can use the ox-texinfo+.el
style for most or all definitions but use the additional flexibility of
ox-texinfo.el, when that is needed.

What do you think?  Might this be something that could be merged?

The reason I am bringing this up now after years of maintaining this as
an extension is that I would like to finally stop checking in both the
*.org and *.texi files into git.  [Non]GNU Elpa already supports this
and I plan to implement it for Melpa as well.  It would be much nicer if
the only additional requirement for an *elpa was to have a recent enough
Org version installed, instead of that and also ox-texinfo+.el.

     Cheers,
     Jonas


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

* Re: Merging ox-texinfo+ into ox-texinfo
  2021-11-09 18:01 Merging ox-texinfo+ into ox-texinfo Jonas Bernoulli
@ 2021-11-19 12:46 ` Nicolas Goaziou
  2021-11-20 21:06   ` Jonas Bernoulli
  0 siblings, 1 reply; 5+ messages in thread
From: Nicolas Goaziou @ 2021-11-19 12:46 UTC (permalink / raw)
  To: Jonas Bernoulli; +Cc: emacs-orgmode

Hello,

Jonas Bernoulli <jonas@bernoul.li> writes:

> I recently talked to Bastien about this and he encouraged to bring up
> the possibility of merging ox-texinfo+.el into ox-texinfo.el.
>
> ox-texinfo+ (https://github.com/tarsius/ox-texinfo-plus) has several
> features but the one I would like to talk about now is the following.

[...]
>
>    Create `@deffn` and similar definition items by writing list
>    items in Org that look similar to what they will look like in
>    Info.  To enable this, add:
>
>    #+TEXINFO_DEFFN: t
>
>    to your Org file.  After doing that, you can create definition
>    items like so:
>
>    - Command: magit-section-show
>
>      Show the body of the current section.
>
>    - Function: magit-git-exit-code &rest args
>    - Macro: magit-insert-section &rest args
>    - Variable: magit-display-buffer-noselect
>    - User Option: magit-display-buffer-function
>    - Key: q, magit-mode-bury-buffer
>
> I propose that we add this as an optional feature to ox-texinfo.el
> itself.

I like the idea, thank you for suggesting it.

The chosen UI is rather odd however. I cannot think of another use of
controlling export thhough "#+keyword: boolean" syntax. Usually, we
extend the "options" keyword. It could become, for example:

  #+options: texinfo+:t

Could it be possible to use that syntax instead?

> It is possible to mix the two styles; you can use the ox-texinfo+.el
> style for most or all definitions but use the additional flexibility of
> ox-texinfo.el, when that is needed.

How is it possible? Keywords are global. How do you change value
locally?

Regards,
-- 
Nicolas Goaziou


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

* Re: Merging ox-texinfo+ into ox-texinfo
  2021-11-19 12:46 ` Nicolas Goaziou
@ 2021-11-20 21:06   ` Jonas Bernoulli
  2021-11-21 12:41     ` Nicolas Goaziou
  0 siblings, 1 reply; 5+ messages in thread
From: Jonas Bernoulli @ 2021-11-20 21:06 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
> I like the idea, thank you for suggesting it.

Great :D

>>    #+TEXINFO_DEFFN: t
>
> The chosen UI is rather odd however. I cannot think of another use of
> controlling export thhough "#+keyword: boolean" syntax. Usually, we
> extend the "options" keyword. It could become, for example:
>
>   #+options: texinfo+:t
>
> Could it be possible to use that syntax instead?

Of course.  I probably used the separate keyword because all the entries
for ox-texinfo's :options-alist did that too, but if that's not how this
is usually done for booleans, then I see no reason not to change it.

>> It is possible to mix the two styles; you can use the ox-texinfo+.el
>> style for most or all definitions but use the additional flexibility of
>> ox-texinfo.el, when that is needed.
>
> How is it possible? Keywords are global. How do you change value
> locally?

Well... it turned out not to be true, but I should be able to get it to
work.  The idea is that the new shorthand handling is only used if such
a shorthand is actually used by the item that is being processed.  All
other list items should effectively be treated as before, but that isn't
the case yet.  For now all non-shorthand list items are simply treated
as @item, but `org-texinfo+-item' could be changed to instead fall back
to the `org-texinfo-item's default behavior in those cases.  (It would
still have to check whether it needs to begin and/or end the "item
container" (itemize/table/...), so it is not completely trivial, but
should be doable.)

For testing purposes I have moved the relevant `ox-texinfo+.el' code
into `ox-texinfo.el', changing only how the feature has to be enabled,
and everything that worked before continues to work.  If the feature is
enabled, then my manuals are exported the same as before and with the
feature disabled org-manual.org also results in the same texi file as
before.

So I have to address the above issue and then we also have to think
about naming.  I was thinking about using the term "shorthands"; instead
of "texinfo-deffn:t" we could use "texinfo-shorthands:t".  The functions
need to be renamed too of course, but IMO simply replacing "ox-texinfo+"
with "ox-texinfo-shorthand" is quite ugly.  Do you have a suggestion for
that?  All the new functions could be placed in the "Item" section.

     Jonas


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

* Re: Merging ox-texinfo+ into ox-texinfo
  2021-11-20 21:06   ` Jonas Bernoulli
@ 2021-11-21 12:41     ` Nicolas Goaziou
  2021-11-30 16:58       ` Jonas Bernoulli
  0 siblings, 1 reply; 5+ messages in thread
From: Nicolas Goaziou @ 2021-11-21 12:41 UTC (permalink / raw)
  To: Jonas Bernoulli; +Cc: emacs-orgmode

Hello,

Jonas Bernoulli <jonas@bernoul.li> writes:

> Of course.  I probably used the separate keyword because all the entries
> for ox-texinfo's :options-alist did that too, but if that's not how this
> is usually done for booleans, then I see no reason not to change it.

More precisely, there's an historical distinction between string values
and other values (symbols, numbers...). The former is set by keywords,
the latter is obtained with "options". Consequently, all the entries in
ox-texinfo's :options-alist are used to set strings.

> Well... it turned out not to be true, but I should be able to get it to
> work.  The idea is that the new shorthand handling is only used if such
> a shorthand is actually used by the item that is being processed.  All
> other list items should effectively be treated as before, but that isn't
> the case yet.  For now all non-shorthand list items are simply treated
> as @item, but `org-texinfo+-item' could be changed to instead fall back
> to the `org-texinfo-item's default behavior in those cases.  (It would
> still have to check whether it needs to begin and/or end the "item
> container" (itemize/table/...), so it is not completely trivial, but
> should be doable.)

Then I suggest to use "attr_texinfo" keyword, for example:

   #+attr_texinfo: :shorthand t
   - item...

This way, we ensure the change is local. `org-texinfo-item' already
checks :sep attribute.

In this case, there's no need to add a new keyword or extend "options".
   
> So I have to address the above issue and then we also have to think
> about naming.  I was thinking about using the term "shorthands"; instead
> of "texinfo-deffn:t" we could use "texinfo-shorthands:t".  The functions
> need to be renamed too of course, but IMO simply replacing "ox-texinfo+"
> with "ox-texinfo-shorthand" is quite ugly.  Do you have a suggestion for
> that?  All the new functions could be placed in the "Item" section.

I see no reason to change the prefix, since these functions are part of
ox-texinfo. I didn't look closely at your code, tho, so I may be wide of
the mark.

WDYT?

Regards,
-- 
Nicolas Goaziou


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

* Re: Merging ox-texinfo+ into ox-texinfo
  2021-11-21 12:41     ` Nicolas Goaziou
@ 2021-11-30 16:58       ` Jonas Bernoulli
  0 siblings, 0 replies; 5+ messages in thread
From: Jonas Bernoulli @ 2021-11-30 16:58 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode

Sorry for the delay, I got side-tracked with many other things.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>>> It is possible to mix the two styles;
>>
>> Well... it turned out not to be true, but I should be able to get it
>> to work.
>
> Then I suggest to use "attr_texinfo" keyword, for example:
>
>    #+attr_texinfo: :shorthand t
>    - item...
>
> This way, we ensure the change is local. `org-texinfo-item' already
> checks :sep attribute.

I am sure I can get it to work just fine without a need for that.
It just turns out that I haven't done so yet, because I only used the
ox-texinfo+ style in manuals that use that style exclusively.  Now
that you have signaled that there is a good change that this would be
included in Org, putting in the work to use both styles in parallel is
actually justified.

But it likely will be a few weeks until I get to work because I looked
at the current implementation again and decided that it would be better
to start over and do the work using org-element instead of at the latest
possible moment when strings are being concatenated as ox-texinfo+
currently does.

> I see no reason to change the prefix, since these functions are part of
> ox-texinfo. I didn't look closely at your code, tho, so I may be wide of
> the mark.

I haven't started working on the org-element based implementation yet,
but I expect that won't actually need any new function definitions so,
the question is moot anyway.  (But just in case: I agree.)

     Cheers,
     Jonas


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

end of thread, other threads:[~2021-11-30 17:04 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-11-09 18:01 Merging ox-texinfo+ into ox-texinfo Jonas Bernoulli
2021-11-19 12:46 ` Nicolas Goaziou
2021-11-20 21:06   ` Jonas Bernoulli
2021-11-21 12:41     ` Nicolas Goaziou
2021-11-30 16:58       ` Jonas Bernoulli

Code repositories for project(s) associated with this 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).