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?
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:
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
EDIT: And here’s the result with that variable set to 0:
I only made the change to the Makefile to test it. I didn’t add it to the build system. For the Makefile:
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?
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
@@ -213,6 +213,11 @@ HTMLDIR_CSS = $(OCTAVE_HTML_DIR)/octave.
+## 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.
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'
--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
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.
@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?