unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
From: Jonas Bernoulli <jonas@bernoul.li>
To: 45435@debbugs.gnu.org
Cc: Stefan Monnier <monnier@iro.umontreal.ca>
Subject: bug#45435: Additional libraries required by transient and magit manuals
Date: Fri, 25 Dec 2020 20:51:20 +0100	[thread overview]
Message-ID: <87r1nd8y13.fsf@bernoul.li> (raw)

I wrote magit's info manual using an org file before org-mode itself
switched the input format of its own manual from texinfo to org.  At
the time it was necessary to improve upon "ox-texinfo.el" to make it
suitable for a large manual.

While that may not be the cases anymore, I have kept using my extended
exporter implemented in "ox-texinfo+.el" and would like to keep doing
so.

I am guessing that [non]gnu elpa currently use the version of org that
comes with Emacs.  It would be nice if we could also use the libraries
in org's "contrib/lisp/" directory.

Transient's manual needs "ox-extra.el" library from that directory.
Magit's additionally needs "org-man.el".

"ox-texinfo+.el" is not part of org's "contrib/lisp/" directory and
would have to be added separately to the machines that build the gnu
and nongnu and elpas.

I would need it for the following three features:

;; 1. 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

;; 2. Optionally share a section's node with some or all of its child
;;    sections.  By default every section on every level gets its own
;;    node, and `ox-texinfo' provides no mechanism for changing that.
;;    To place a section in the same node as its parent section, do
;;    this:
;;
;;      **** Log Performance
;;      :PROPERTIES:
;;      :NONODE: t
;;      :END:

;; 3. Optionally modify the Org file before exporting it.  This is
;;    implemented using a hook that can be set using the `BIND'
;;    property:
;;
;;      #+BIND: ox-texinfo+-before-export-hook some-function
;;      #+BIND: ox-texinfo+-before-export-hook another-function
;;
;;    The function `ox-texinfo+-update-version-strings' is provided
;;    as an example.  It makes some assumptions that might not be
;;    appropriate for your manuals, so you might have to define your
;;    own variant.

(The third feature can also be invoked using a make target and this needs
some love to work properly with "elpa-admin.el", but that's a detail.)

You can use git or a browser to get "ox-texinfo+.el" from
https://github.com/tarsius/ox-texinfo-plus.

Please consider making "org/contrib/lisp/" and "ox-texinfo+.el"
available to the elpas.

     Jonas





             reply	other threads:[~2020-12-25 19:51 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-12-25 19:51 Jonas Bernoulli [this message]
2020-12-26 21:02 ` bug#45435: Additional libraries required by transient and magit manuals Stefan Monnier
2020-12-27 12:49   ` Jonas Bernoulli
2020-12-27 15:58     ` Stefan Monnier

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87r1nd8y13.fsf@bernoul.li \
    --to=jonas@bernoul.li \
    --cc=45435@debbugs.gnu.org \
    --cc=monnier@iro.umontreal.ca \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.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).