RFE: make systemd.directives html pages jump to the anchor in the target #1956
Labels
Comments
poettering
added
RFE 🎁
|
@keszybz is our XML guru! Any idea if we can get that done? |
keszybz
added a commit
to keszybz/systemd
that referenced
this issue
Nov 23, 2015
Links like http://www.freedesktop.org/software/systemd/man/systemd.socket.html are changed to http://www.freedesktop.org/software/systemd/man/systemd.socket.html#Accept=. This implementation is quick & dirty, and misses various corner cases. A fairly important one is that when a few directives share the same anchor (which happens when multiple directives are described in the same paragraph), generated links for everything except the first one link to an invalid anchor. Another shortcoming is that the formatting does not use the proper generateID machinery, so the anchor name could be wrong in some cases. But it seems to work for a large percentage of links, so seems to be an improvement in usability. When the anchor is missing, we land at the top of the page, which is the same as before. If the anchor were to point to different spot, this would be more confusing... Not sure if that ever happens. Anyway, the user should be able to recover from landing on the wrong place in the page. (Mostly) fixes systemd#1956.
|
I'm pretty sure that nobody really understands that stuff :) But in this case it seems fairly easy to get 90% of the problem done. Maybe @cmacq2 has some better idea. |
cmacq2
added a commit
to cmacq2/systemd
that referenced
this issue
Nov 30, 2015
…sheets. man: redo support for cross references to close numerous edge cases and fix buggy behaviour. This change introduces helper templates for: - permalink-id-scheme-html.xsl : splits out support for ID conflict resolution and permalinks (anchors). - cross-refs-html.xsl : implements support for cross references to other systemd man pages. The new cross reference logic replaces previous commit: 958caa5 It addresses Github issue systemd#1956: systemd#1956 'RFE: make systemd.directives html pages jump to the anchor in the target' This version should fix the following issues inherent in the previous 'guessing' implementation: - Because of the fact the inline.seq DocBook template is used when generating values for id attributes (arguably broken), the value of a @target attribute cannot be assumed to correspond to the (sub)section ID even if it is otherwise entirely correct. E.g.: "--address=" from 'command line options' in systemd.directives (@target='--address=') lists a reference to systemd-bus-proxyd(8) but the corresponding section is actually called: "--address=ADDRESS[:ADDRESS...]" which is nonobvious as the square brackets ([]) are not part of the source XML but generated by the inline.seq DocBook template. - In fact, it is not generally safe to assume the ID attributes are, in fact, valid HTML id attributes. For instance some ID attributes contain linebreaks... - Beyond that a fair number of cross references refer to some kind of 'alias' which is not reflected in ID attributes at all. E.g.: "AssertDirectoryNotEmpty=" from 'Unit directives' in systemd.directives (@target='AssertDirectoryNotEmpty=') actually refers to the subsection with ID value 'AssertArchitecture=' in systemd.unit(5). - Also, a number of @target attributes refer to a partial value for the ID attributes. E.g.: "$attr{file}" from 'UDEV Directives' in systemd.directives (@target='$attr{'); Furthermore by noting structural correspondence between the location of a citerefentry and the referenced man page additional cross references are now also picked up on: - Cross references between variablelist structures: e.g. the kernel command line 'quiet' option is described as "Parameter understood by both the kernel and the system and service manager to control console log verbosity. For details, see systemd(1)" Because the systemd page contains a section on the 'quiet' option a direct link to the subsection can be synthesised. We get another step closer to the "ideal" world case described in the RFE. - Similarly, specific markup like filename, option or command elements following or preceding a citerefentry may also be turned into a fully function cross reference, e.g.: "Use machinectl(1)'s login command to request an additional login prompt in a running container." in systemd-nspawn and "(See KillMode= in systemd.kill(5).)" in systemd.socket. - Shorthand references which only supply a partial ID for target attribute or when the logic for the above two cases would otherwise fail to recover the full ID, e.g.: "For details about the format and contents of .nspawn files, consult systemd.nspawn(5)." in systemd-nspawn (using implicit: .nspawn to find '.nspawn File Discovery' in systemd.nspawn); "... with systemd-nspawn's --settings= switch, see systemd-nspawn(1) for details." in systemd.nspawn (using implicit --settings= to find '--settings=MODE' in systemd-nspawn) - Sometimes command line arguments can be related to subsections as well, for example: "systemd.journald.forward_to_syslog=, systemd.journald.forward_to_kmsg=, systemd.journald.forward_to_console=, systemd.journald.forward_to_wall= Enables/disables forwarding of collected log messages to syslog, the kernel log buffer, the system console or wall. See journald.conf(5) for details" in systemd-journald.service is related to the 'ForwardToSyslog=' section of journald.conf Below follows a high level overview of the extra logic introduced to the code: Support for cross references to anchor tags is divided into two general cases: 1. The explicit case, in which the source docbook manpage XML contains a relevant @target attribute 2. The implicit case, in which a number of potential substitutes for an explicit @target are attempted. Potential subsitutes are determined by noting various structural patterns in man page source XML. In either case a set of potential 'targets' is obtained. If this set is not empty the potential targets are then matched against the referenced XML by querying it for corresponding source nodes. This query succeeds if at least one XML node from the referenced XML document is returned. The query may fail if either the referenced XML document cannot be loaded, or no corresponding source node is found. In the case the query succeeds, a match is selected (currently the first) and a corresponding value for the fragment portion of the URL is generated by replaying the permalink ID scheme and returning the resulting ID value. Otherwise an empty fragment is returned. Additionally some citerefentry nodes referring to systemd man pages are excluded from this cross reference scheme, to wit: - References to section 3 of the man pages (because these generally refer to documents by an alias which does not exist as XML file) - References in the 'See Also' sections (because these are not intended to refer to subsections) Apart from that, the logic for references in general has been refactored to condense the code and fixed so URLs generated omit the hash (#) if the fragement value is empty. Finally, the parameter cross.refs.debug is introduced which can be used to generate some debug output following the hyperlink. This can be enabled by passing a non zero number for XSLT_DEBUG_CROSS_REFS when calling make, e.g.: make XSLT_DEBUG_CROSS_REFS=1
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
currently when you click on a link from http://www.freedesktop.org/software/systemd/man/systemd.directives.html
say, the first one, Accept=, it currently goes to http://www.freedesktop.org/software/systemd/man/systemd.socket.html
it would be useful if it went to http://www.freedesktop.org/software/systemd/man/systemd.socket.html#Accept=
(i don't know dockbook nor if that is easy)
The text was updated successfully, but these errors were encountered: