Re: Provide sane default for the @direntry

[Ihor Radchenko <yantar92@posteo.net>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> May you please supply a ChangeLog entry? I am not sure if I understand
>> the purpose of each change in the diff.
>>
>> Also, it looks like you introduce some DWIM behaviour for auto-generating
>> @direntry contents. Such new behaviour ought to be documented in the
>> manual and announced in the news.
>
> New patch attached,

Thanks!
See my comments inline.

> * lisp/org/ox-texinfo.el: Remove redundant `:group` arguments.
> Prefer #' to quote function names.

May you please split unrelated changes into a separate patch?

> * doc/misc/org.org (Texinfo specific export settings): Adjust accordingly.

It would be nice to provide etc/ORG-NEWS entry as well.

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

?
  
>  - =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.
  
>      (: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?

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.

> +     ;; Info directory information.  Only supply if category is provided.
> +     ;; FIXME: A Texinfo doc without a direntry is significantly less useful
> +     ;; since it won't appear in the main Info-directory, so maybe we should
> +     ;; use a default category like "misc"?

Sounds reasonable. We may add a new custom option with default category.

> +     (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.

> +              (t (format "* %s." file)))))

What if dt is "Foo."?

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