Broken links in docs build

[spwhitton]

Hello,

I'm packaging taxy.el for Debian. I am using this command to rebuild the docs:

emacs -q --batch -f package-initialize -l ox-texinfo --eval '(find-file "README.org")' --eval '(org-texinfo-export-to-info)'

but I get the error

Unable to resolve link: "numbery-starting-basically"

I can resolve this by moving the #+OPTIONS line with broken-links:t up to the top of the file, after #+TITLE. Perhaps it could be so moved upstream? Thanks.

[alphapapa]

Hello,

Well, it seems that there are 3 problems here:

1. The link is not resolved. This is probably because the link in question is one generated with org-make-toc that is intended for rendering by GitHub's Org renderer. Unfortunately, there's no easy way to make links that work both within Org and within their Ruby-based renderer at the same time (at least, that I've discovered). But this might be solvable by using custom entry IDs for the links to point to.
2. The broken-links:t option is not being recognized. I don't know why that would be the case, because it works for me. What Emacs and Org versions are you using?
3. You're rebuilding the Info manual. Why? I do it myself, automatically, when the readme is saved by me, so that it gets installed by Emacs when users install the package directly from the git repo. What is solved by rebuilding it in the Debian package?

As you can see, I have the options line in the section where export settings are kept together, so I'd prefer to keep it there. But if there's no other practical way to solve it, I'll move it so you don't have to keep a patch against the source.

Thanks.

[spwhitton]

Hello,

Debian has Emacs 27.1 right now, and I tried using both the version of Org that comes with Emacs 27.1 and with version 9.5.2, which we also have packaged. In both cases, none of the export options were recognised until I moved them all to the top of the file.

Debian requires that we can rebuild everything using tools that we have packaged, such that we're self-contained. There are lots of extra .org export things like ox-texinfo+ etc. around on GitHub, so the easiest way to ensure that we can indeed rebuild the taxy.el manual is just to do so during the package build.

I'd certainly be grateful for having the option lines moved up, but it's not a big deal for us to carry a patch for this, as I would guess there aren't likely to be merge conflicts.

-- Sean Whitton

[mekeor]

Here's a quote from the Org info manual:

Finally, a ‘COMMENT’ keyword at the beginning of an entry, but after any other keyword or priority cookie, comments out the entire subtree. In this case, the subtree is not exported and no code block within it is executed either[128]. The command below helps changing the comment status of a headline.

[128]: For a less drastic behavior, consider using a select tag (see Export Settings) instead.

This suggests that it is expected behavior that the line #+OPTIONS: broken-links:t *:t within the * COMMENT Export setup section is not respected.

I suggest to remove the COMMENT keyword.

[mekeor]

I just tried out removing the COMMENT keyword: https://github.com/mekeor/taxy.el/tree/4633fa9c0e1bf97678d0cf032924599d04a8c9bb

Unfortunately, when the COMMENT keyword is removed, GitHub will render these sections into HTML. This is really a bug in GitHub actually. (Forgejo, for instance, Codeberg, does not render sections into HTML if they have a noexport tag.)

Personally, I think the best approach is to move these lines to the top of the README.org file:

#+OPTIONS: broken-links:t *:t
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Taxy: (taxy)
#+TEXINFO_DIR_DESC: Programmable taxonomical grouping for arbitrary objects

[alphapapa]

@mekeor Technically a keyword like #+OPTIONS: is not a "code block", and AFAIK the COMMENT keyword does not prevent Org from parsing them. AFAIK the issue is the distance from the beginning/end of the file where the lines are placed.

Yes, the COMMENT keyword is necessary because GitHub's Ruby-based renderer does not match Org in functionality. I have dealt with these issues on many repositories' readmes for years now.