Stefan Monnier <monn...@iro.umontreal.ca> writes: > 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.
If it is not well-documented, we may as well help users by explaining a bit in a footnote in the Org manual. > 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. ... then we can also include this discussion in a footnote and put the new syntax into the main visible part of the manual. > The old(current) situation is arguably worse because it doesn't even > document the syntax that needs to be used. Agree. >>> - =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. Also ok. I do not have a strong opinion here - referring to title is also clear enough for me; I am just not sure if it is clear enough for all the readers of the manual. >>> (: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 can add it after we finalize your patch. Or you can do it as a part of the patch, if you are willing to. (Just make sure that old keyword name is supported for backwards-compatibility) >>> + (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. I had a hard time understanding why the second clause of `cond' never matches things like "Foo (filename)" - the test (equal dt file) looks suspicious from the first glance; until I spend some time parsing the above regexps. So, I am asking you to add code comment explaining why (equal dt file) is sufficient. -- 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>