emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Jonas Bernoulli <jonas@bernoul.li>
Cc: kyle@kyleam.com, emacs-orgmode@gnu.org
Subject: Re: [PATCH 2/2] ox-texinfo: Define definition commands using description lists
Date: Sun, 26 Dec 2021 22:46:51 +0100	[thread overview]
Message-ID: <87sfuf9gz8.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <20211218214038.9459-3-jonas@bernoul.li> (Jonas Bernoulli's message of "Sat, 18 Dec 2021 22:40:38 +0100")

Hello,

Thanks.

Jonas Bernoulli <jonas@bernoul.li> writes:

> +#+begin_example
> +- Key: C-n (do-something) ::
> +  This command does something.
> +
> +- User Option: do-something-somehow ::
> +  This option controls how exactly ~do-something~ does its thing.
> +#+end_example
> +
> +#+texinfo: @noindent
> +becomes
> +
> +#+begin_example
> +@table @asis
> +@item @kbd{C-c C-c} (@code{do-something})
> +@kindex C-c C-c
> +@findex do-something
> +This command does something.
> +@end table

There's a mismatch between the keys.

> +Key items don't have to specify the respective command in parenthesis
> +as done above; that part is optional.

Simply put:

Command in parenthesis, as done above, is optional.

> +Regardless of which approach you use, you must define the =kbd= macro
> +(see [[*Macro Replacement]]), which you can then use anywhere in the Org
> +file:
> +
> +#+begin_example
> +,#+macro: kbd (eval (let ((case-fold-search nil) (regexp (regexp-opt '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words))) (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (replace-regexp-in-string regexp "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t))))
>  #+end_example

Ouch. I don't think we should expect users to define this in order to
use the feature being implemented. IOW, it should work out of the box.

I think the functions responsible for generating the Texinfo code should
handle this without relying on the macro. Of course, if that part is
factored out, the macro might, in turn, make use of it.

> +(defconst org-texinfo--definition-command-regexp
> +  (format "\\`%s: \\(.+\\)"
> +          (regexp-opt
> +           (delq nil (mapcar #'cdr org-texinfo--definition-command-alist))
> +           1))

What is 1 meaning here? Do you mean t?


> +(defun org-texinfo--separate-definitions (tree _backend info)
> +  "Split up descriptive lists that contain Texinfo definition
> commands."

You need to document the arguments.
> +  (org-element-map tree 'plain-list
> +    (lambda (plain-list)
> +      (when (eq (org-element-property :type plain-list) 'descriptive)
> +        (let ((contents (org-element-contents plain-list))
> +              item items)

Nitpick: (items nil)

> +          (while (setq item (pop contents))

nitpick: Use dolist.

> +            (pcase-let ((`(,cmd . ,args) (org-texinfo--match-definition item)))
> +              (cond
> +               (cmd
> +                (when items
> +                  (org-texinfo--split-plain-list plain-list (nreverse items))
> +                  (setq items nil))
> +                (org-texinfo--split-definition plain-list item cmd args))
> +               (t
> +                (when args
> +                  (org-texinfo--massage-key-item plain-list item args))
> +                (push item items)))))
> +          (unless (org-element-contents plain-list)
> +            (org-element-extract-element plain-list)))))
> +    info)
> +  tree)
> +
> +(defun org-texinfo--match-definition (item)
> +  "Return a cons-cell if ITEM specifies a Texinfo definition command.
> +The car is the command and the cdr is its arguments."
> +  (let ((tag (car-safe (org-element-property :tag item))))
> +    (and tag
> +         (stringp tag)
> +         (string-match org-texinfo--definition-command-regexp tag)
> +         (pcase-let*
> +             ((cmd (car (rassoc (match-string-no-properties 1 tag)
> +                                 org-texinfo--definition-command-alist)))
> +              (`(,cmd ,category)
> +               (and cmd (save-match-data (split-string cmd " "))))
> +              (args (match-string-no-properties 2 tag)))
> +           (cons cmd (if category (concat category " " args) args))))))
> +
> +(defun org-texinfo--split-definition (plain-list item cmd args)
> +  "Insert a definition command before list PLAIN-LIST.
> +Replace list item ITEM with a special-block that inherits the
> +contents of ITEM and whose type and Texinfo attributes are
> +specified by CMD and ARGS."
> +  (let ((contents (org-element-contents item)))
> +    (org-element-insert-before
> +     (apply #'org-element-create 'special-block
> +            (list :type cmd
> +                  :attr_texinfo (list (format ":options %s" args))
> +                  :post-blank (if contents 1 0))
> +            (mapc #'org-element-extract-element contents))
> +     plain-list))
> +  (org-element-extract-element item))
> +
> +(defun org-texinfo--split-plain-list (plain-list items)
> +  "Insert a new plain list before the plain list PLAIN-LIST.
> +Remove ITEMS from PLAIN-LIST and use them as the contents of the
> +new plain list."
> +  (org-element-insert-before
> +   (apply #'org-element-create 'plain-list
> +          (list :type 'descriptive :post-blank 1)
> +          (mapc #'org-element-extract-element items))
> +   plain-list))
> +
> +(defun org-texinfo--massage-key-item (plain-list item args)
> +  "In PLAIN-LIST modify ITEM based on ARGS.
> +Reformat ITEM's tag property and add findex and kindex entries to
> +its content.  If the bullet is \"+\" then use \"@itemx\" and deal with
> +data from preceeding siblings that use such a bullet."
> +  (let (key cmd)
> +    (if (string-match " +(\\([^()]+\\)) *\\'" args)

Could you use `rx' here?

> +        (setq key (substring args 0 (match-beginning 0))
> +              cmd (match-string 1 args))
> +      (setq key args))
> +    (org-element-put-property
> +     item :tag
> +     (nconc (if (assoc "kbd" org-macro-templates)
> +                (let ((templates org-macro-templates))
> +                  (with-temp-buffer
> +                    (insert (format "{{{kbd(%s)}}}" key))

Here, there could be a function building the key chord, and you could
wrap the result into a raw string (see `org-export-raw-string').

Regards,
-- 
Nicolas Goaziou


  reply	other threads:[~2021-12-26 21:48 UTC|newest]

Thread overview: 47+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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
2021-12-18 21:40         ` [PATCH 0/2] ox-texinfo: Define definition commands using description lists Jonas Bernoulli
2021-12-18 21:40           ` [PATCH 1/2] ox-texinfo: Turn a description list item with "+" bullet into @itemx Jonas Bernoulli
2021-12-26 21:37             ` Nicolas Goaziou
2021-12-27 18:05               ` Jonas Bernoulli
2021-12-30  9:40                 ` Nicolas Goaziou
2022-01-05 13:12                   ` Jonas Bernoulli
2022-01-23 15:01                   ` Jonas Bernoulli
2021-12-18 21:40           ` [PATCH 2/2] ox-texinfo: Define definition commands using description lists Jonas Bernoulli
2021-12-26 21:46             ` Nicolas Goaziou [this message]
2021-12-27 18:05               ` Jonas Bernoulli
2021-12-30  0:57                 ` Nicolas Goaziou
2022-01-05 13:16                   ` Jonas Bernoulli
2022-01-05 13:30           ` [PATCH v2 0/3] " Jonas Bernoulli
2022-01-05 13:30             ` [PATCH v2 1/3] ox-texinfo: Add function for use by kbd macro Jonas Bernoulli
2022-01-05 13:30             ` [PATCH v2 2/3] ox-texinfo: Optionally use @itemx for certain description list items Jonas Bernoulli
2022-01-05 13:30             ` [PATCH v2 3/3] ox-texinfo: Define definition commands using description lists Jonas Bernoulli
2022-01-14 23:01             ` [PATCH v2 0/3] " Jonas Bernoulli
2022-01-18 15:11           ` [PATCH v3 " Jonas Bernoulli
2022-01-18 15:11             ` [PATCH v3 1/3] ox-texinfo: Add function for use by kbd macro Jonas Bernoulli
2022-01-22 15:19               ` Nicolas Goaziou
2022-01-18 15:11             ` [PATCH v3 2/3] ox-texinfo: Optionally use @itemx for certain description list items Jonas Bernoulli
2022-01-22 15:33               ` Nicolas Goaziou
2022-01-23  1:26                 ` Jonas Bernoulli
2022-01-23 20:43                 ` Jonas Bernoulli
2022-01-18 15:11             ` [PATCH v3 3/3] ox-texinfo: Define definition commands using description lists Jonas Bernoulli
2022-01-23  0:02               ` Nicolas Goaziou
2022-01-23  1:14                 ` Jonas Bernoulli
2022-01-23 14:45                 ` Jonas Bernoulli
2022-01-23 20:27           ` [PATCH v4 0/3] " Jonas Bernoulli
2022-01-23 20:27             ` [PATCH v4 1/3] ox-texinfo: Add function for use by kbd macro Jonas Bernoulli
2022-01-23 20:27             ` [PATCH v4 2/3] ox-texinfo: Optionally use @itemx for certain description list items Jonas Bernoulli
2022-01-23 21:17               ` Jonas Bernoulli
2022-01-23 20:27             ` [PATCH v4 3/3] ox-texinfo: Define definition commands using description lists Jonas Bernoulli
2022-01-31 23:45           ` [PATCH v5 0/4] " Jonas Bernoulli
2022-01-31 23:45             ` [PATCH v5 1/4] ox-texinfo: Add function for use by kbd macro Jonas Bernoulli
2022-01-31 23:45             ` [PATCH v5 2/4] ox-texinfo: Optionally use @itemx for certain description list items Jonas Bernoulli
2022-01-31 23:45             ` [PATCH v5 3/4] ox-texinfo: Define definition commands using description lists Jonas Bernoulli
2022-01-31 23:45             ` [PATCH v5 4/4] ox-texinfo: Allow enabling compact syntax for @itemx per file Jonas Bernoulli
2022-02-08 23:46             ` [PATCH v5 0/4] ox-texinfo: Define definition commands using description lists Nicolas Goaziou
2022-02-11 20:01               ` Jonas Bernoulli
2022-02-15 21:01               ` [PATCH] etc/ORG-NEWS: Add news items about new features in texinfo exporter Jonas Bernoulli
2022-02-22 19:14                 ` Nicolas Goaziou

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.orgmode.org/

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

  git send-email \
    --in-reply-to=87sfuf9gz8.fsf@nicolasgoaziou.fr \
    --to=mail@nicolasgoaziou.fr \
    --cc=emacs-orgmode@gnu.org \
    --cc=jonas@bernoul.li \
    --cc=kyle@kyleam.com \
    --subject='Re: [PATCH 2/2] ox-texinfo: Define definition commands using description lists' \
    /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

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).