From: Stefan Monnier <monnier@iro.umontreal.ca>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: emacs-orgmode@gnu.org
Subject: Re: Provide sane default for the @direntry
Date: Mon, 04 Mar 2024 11:16:22 -0500 [thread overview]
Message-ID: <jwvedcq7zzq.fsf-monnier+emacs@gnu.org> (raw)
In-Reply-To: <871q8q1cfd.fsf@localhost> (Ihor Radchenko's message of "Mon, 04 Mar 2024 11:09:10 +0000")
>> * doc/misc/org.org (Texinfo specific export settings): Adjust accordingly.
> It would be nice to provide etc/ORG-NEWS entry as well.
Yes, thanks.
>> #+cindex: @samp{TEXINFO_DIR_TITLE}, keyword
>> The directory title of the document.
>> + This is the short name under which the ~m~ command will find your
>> + manual in the main Info directory. It defaults to the base name of
>> + the Texinfo file.
>> +
>> + If you need more control, it can also be the full entry using the
>> + syntax ~* TITLE: (FILENAME).~.
>
> This example is a bit confusing. How will it look like in Org document?
> #+TEXINFO_DIR_TITLE: * title: (filename). ?
> If yes, it is confusing because you just mention that default value is
> filename, but you have both "title" and "filename" in the example.
>
> Maybe
>
> : #+TEXINFO_DIR_TITLE: * name: (filename).
>
> ?
[ Calling it "TITLE" is definitely confusing, I should use DIRTITLE. ]
And yes, the Texinfo syntax is either
* FILENAME.
or
* DIRTITLE: (FILENAME).
[ where FILENAME which should be the file name without the
`.info` extension). ]
so I think it makes a lot sense for DIRTITLE to default to FILENAME?
The "* DIRTITLE: (FILENAME)." syntax is Texinfo's syntax, and currently the
Org user needs to know that syntax and abide by it (even though it's
not well defined nor well documented, IME). My change mostly makes it
unnecessary for the user to know that syntax because ox-texinfo already
knows the FILENAME, so it only needs the DIRTITLE.
The new code supports the "* DIRTITLE: (FILENAME)." syntax mostly for
backward compatibility, tho it can also be useful in corner cases such
as when the final filename will be different than the one ox-texinfo
knows about.
Not sure how to adjust the text to clarify that, without including
a discussion of the "* DIRTITLE: (FILENAME)." and how things used to be,
and how the filename is controlled.
The old(current) situation is arguably worse because it doesn't even
document the syntax that needs to be used.
>> - =TEXINFO_DIR_DESC= ::
>>
>> #+cindex: @samp{TEXINFO_DIR_DESC}, keyword
>> The directory description of the document.
>> + Defaults to the title of the document.
>
> I'd also add that it should be a short sentence.
Not sure if it needs to be a sentence, but yes, it should usually be
short tho I don't think there's a technical need for it, so I think the
"defaults to the title" should be a good enough hint about the kind of
length expected.
>> (:texinfo-dircat "TEXINFO_DIR_CATEGORY" nil nil t)
>> + ;; FIXME: The naming of these options is unsatisfactory:
>> + ;; TEXINFO_DIR_DESC corresponds (and defaults) to the document's
>> + ;; title, whereas TEXINFO_DIR_TITLE corresponds (and defaults) to
>> + ;; its filename.
> What about TEXINFO_DIR_NAME + TECINFO_DIR_DESC?
Fine by me, yes.
> I do not see a big problem with description defaulting to document title
> given that it should be a short sentence - an equivalent of proper
> document title.
I don't see a problem with it either. The problem is mostly in the
DIR_TITLE name suggesting it should be like the title rather than the
indexing keyword that it is.
>> + (let* ((dircat (plist-get info :texinfo-dircat))
>> + (dt (plist-get info :texinfo-dirtitle))
>> + (file (file-name-sans-extension
>> + (or (org-strip-quotes (plist-get info :texinfo-filename))
>> + (plist-get info :output-file))))
>> + (dirtitle
>> + (cond
>> + ((and dt
>> + (or (string-match "\\`\\* \\(.*?\\)\\(\\.\\)?\\'" dt)
>> + (string-match "\\`\\(.*(.*)\\)\\(\\.\\)?\\'" dt)))
>> + ;; `dt' is already "complete".
>> + (format "* %s." (match-string 1 dt)))
>> + ((and dt (not (equal dt file)))
>> + (format "* %s: (%s)." dt file))
>
> It would be nice to add a comment saying that dt values like
> "Foo (filename)" are already captured by the previous cond clause.
I don't understand what you mean by that.
>> + (t (format "* %s." file)))))
>
> What if dt is "Foo."?
Good point.
Stefan
next prev parent reply other threads:[~2024-03-04 16:17 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-02-28 0:19 Provide sane default for the @direntry Stefan Monnier
2024-02-28 10:35 ` Ihor Radchenko
2024-03-02 20:01 ` Stefan Monnier
2024-03-04 11:09 ` Ihor Radchenko
2024-03-04 16:16 ` Stefan Monnier [this message]
2024-03-05 12:49 ` Ihor Radchenko
2024-03-05 19:27 ` Stefan Monnier
2024-03-06 11:17 ` Ihor Radchenko
2024-03-06 15:00 ` Stefan Monnier
2024-03-07 13:46 ` Ihor Radchenko
2024-03-08 8:09 ` Stefan Monnier
2024-03-08 10:49 ` Ihor Radchenko
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=jwvedcq7zzq.fsf-monnier+emacs@gnu.org \
--to=monnier@iro.umontreal.ca \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@posteo.net \
/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/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).