Are carriage return markers in Qt documentation browser necessary?

I happened to be using the GUI, which I almost never do, and I happened to look at the documentation for Octave functions. I see carriage return marks wherever there was a @deftypefn macro in the Texinfo documentation. This doesn’t seem necessary to me. Is there a way to avoid it? Are other users seeing this?

Screenshot below:

image

and strangely they appear as clickable links too. i see it in octave 7.2.0, don’t have anything older sitting around to look back at to see when/where that might have started.

Octave 6.4.0 GUI on Fedora 36:

image

(And I confirm the paragraph marks in 7.2.0 on Fedora 37)

Here is the Texinfo maintainers discussion where they added that feature: Re: HTML self links to anchor points

It seems someone wanted a visible token that had an HTML link that they could then copy-paste elsewhere.

It says Turn it off with the -c PERMALINKS=0 option (variable name subject to change).

EDIT: Tracked it to the Texinfo manual GNU Texinfo 7.0

COPIABLE_LINKS

If set, output copiable links for the definition commands (see
Definition Commands) and table commands (see Making a Two-column
Table) where an index entry is defined. A link appears as a ‘¶’ sign that
appears when you hover the mouse pointer over the heading text.

EDIT: For Texinfo 7.0, passing --set-customization-variable 'COPIABLE_LINKS 0' to Texinfo is supposed to cause those pilcrow marks to disappear – is that what is desired?

EDIT: For Texinfo 6.8 and older, the variable was called COPIABLE_ANCHORS. From info texinfo:

‘COPIABLE_ANCHORS’
If set, output copiable anchors for the definition commands (*note
Definition Commands) and table commands (*note Two-column
Tables) where an index entry is defined. An anchor appears as a
‘¶’ sign that appears when you hover the mouse pointer over the
heading text.

EDIT: And here’s the result with that variable set to 0:

nopilcrow

I only made the change to the Makefile to test it. I didn’t add it to the build system. For the Makefile:

MAKEINFOHTML = $(MAKEINFO) --html --set-customization-variable 'COPIABLE_ANCHORS 0'

Then the links will not be clickable, will they?

Actual links in the doc are clickable whether that variable is set to true or false. But without it, it doesn’t add a pilcrow at the end of the def lines with a link like this: #index-accumarray-4.

I suppose it’s useful only if one is sharing specific sections online. For example:

Go here Accumulation (GNU Octave (version 6.1.0)) and hover on the function definition line accumarray. Nothing happens.

Go here Accumulation (GNU Octave (version 7.3.0)) and hover on accumarray, and a linked pilcrow appears.

It seems that the doc accumarray system makes those tags available and visible always…

I cannot click in 6.1.0 docs…

Not sure what you mean by “cannot click”. In 6.1, if you see the link to unique a little lower down in that page, it takes you to Sets (GNU Octave (version 6.1.0))

In 7.3 also it correspondingly takes you to Sets (GNU Octave (version 7.3.0))

The only thing that’s missing is the self-link at the end of the function definition line.

The self-link doesn’t seem useful to me. When I click it, the screen scrolls so that line is at the top of the page, but that’s it. I would be in favor of setting the customization variable during document creation to suppress this.

I admit I don’t know the use case. If someone wanted to share a link to the doc online, aimed at going directly to a specific function on a long page, it could be useful, but (a) it’s unclear if that’s a common use, and (b) only the first deftypefn needs the anchor, not all the followup deftypefnx. (Edit: on second thought, someone might want to share a specific invocation form, so this might be of use.)

If you want fine grain control I suppose the online doc could be built with that enabled and the local one disabled?

E.g. you also can save links like
https://docs.octave.org/v7.3.0/Accumulation.html#index-accumarray-1
and use them in some other documents

1 Like

I don’t think it is a common use, and we aren’t supporting it in Texinfo. While you could make use of this feature in HTML, you can’t do it in an Info browser. The Octave documentation always produces an anchor to the top of the function. That’s about all I, personally, think one needs.

I think the best case would be to disable those anchors by default (Note: Texinfo 6.8 and 7 use different keywords) but enable it to the build system for the online build alone since that will be in HTML anyway, not info or doc.

This feels like a lot of work for little gain. The person who prepares the HTML documentation for the Web will need a different Makefile target, and remember to use it. But, since I don’t do that part of the Octave release process I’ll let whoever does do that decide whether they want to support that.

For the default case, I tried this patch

diff --git a/doc/interpreter/module.mk b/doc/interpreter/module.mk
--- a/doc/interpreter/module.mk
+++ b/doc/interpreter/module.mk
@@ -213,6 +213,11 @@ HTMLDIR_CSS = $(OCTAVE_HTML_DIR)/octave.
 
 endif
 
+## Suppress carriage return at end of @deftypefn macros in HTML.
+## Placed outside of 'if AMCOND_BUILD_DOCS' so that Automake variable is
+## always initialized.
+AM_MAKEINFOHTMLFLAGS = --set-customization-variable 'COPIABLE_ANCHORS 0' --set-customization-variable 'COPIABLE_LINKS 0'
+
 ## Even if Octave was configured with --disable-docs, we will install
 ## OCTAVE_QTHELP_FILES if they already exist.
 

html.diffs (612 Bytes)

It’s not perfect because it throws a warning with Texinfo 6.8 about COPIABLE_LINKS variable. Presumabliy Texinfo 7.0 will do the same about COPIABLE_ANCHORS.

I think that’s OK – if the online HTML doc can’t be automated, instead of pasting a link to a function in the help forum for any user who needs it, I can always copy-paste the help text. That was the only use case I could think of for myself though.

Consider “paragraph mark” or maybe “pilcrow” instead of “carriage return” for the comment. To me a carriage return is like ASCII 13 or \r. Or you could copy-paste a literal into that comment to avoid naming it.

I’ll do that. Next question is how to decide between

--set-customization-variable 'COPIABLE_ANCHORS 0'
OR
--set-customization-variable 'COPIABLE_LINKS 0'

@jwe: Is it okay to check for a version number in configure? Version 6.8 and below uses pattern #1 and version 7.0 and above uses pattern #2. One could write a configure test which calls makeinfo --version and then parses the result.

If you think it is really important to only check for features I can call

makeinfo --set-customization-variable 'COPIABLE_LINKS 0'

and parse the output. For my Texinfo copy 6.8 this throws a warning:

makeinfo: warning: set_from_cmdline: unknown variable COPIABLE_LINKS

EDIT (11/15/22): As @mmuetzel pointed out, the warning message will differ based on locale which is a small push towards just checking the version number. On the other hand, it still wouldn’t be hard to parse the warning for the keywords “set_from_cmdline” and “COPIABLE_LINKS” and avoid the words that depend on locale.

I don’t know if there are still (old) pre-processors out there that could stumble upon encountering such an (presumably UTF-8 encoded) non-ASCII character. The behavior might also depend on the system locale.
It might be best to only use ASCII characters in the sources (if possible) - including the comments.

Could it be the attempt to create a permalink feature, rather than an encoding issue, like @dasergatskov pointed out before?

I often work with Sphinx, a more modern doc generator, and this is standard there:

If the feature is working, I would love to see it in Octave as well. Especially this is helpful, when pointing users to a specific part of the documentation.

@siko1056 It is possible to override the variables to 1 instead of 0 in the Makefile. How is the documentation built for docs.octave.org? Is it feasible to have a second Makefile for that system with the variables set to 1?

Given that there seem to be use cases for both, is it worth adding a configure option like --enable-doc-links?