Req #77018 [Opn]: Generate 'link' elements in HTML head, for rel="next", "prev", "up", "start"
| From: | phil at catalyst dot net dot nz | Date: | Wed, 17 Oct 2018 03:00:23 +0000 |
| Subject: | Req #77018 [Opn]: Generate 'link' elements in HTML head, for rel="next", "prev", "up", "start" | ||
| References: | 1 | Groups: | php.doc.bugs |
| Request: | Send a blank email to doc-bugs+get-16086@lists.php.net to get a copy of this message | ||
Edit report at https://bugs.php.net/bug.php?id=77018&edit=1
ID: 77018
User updated by: phil at catalyst dot net dot nz
Reported by: phil at catalyst dot net dot nz
Summary: Generate 'link' elements in HTML head, for
rel="next", "prev", "up", "start"
Status: Open
Type: Feature/Change Request
Package: Doc Build problem
PHP Version: master-Git-2018-10-16 (Git)
Block user comment: N
Private report: N
New Comment:
Correction: Make the final line of that perl script this:
$&|s
i.e. Add the "s" modifier. It turns out that there are some pages where the nav titles
span multiple lines, and . does not match a newline without this modifier.
Previous Comments:
------------------------------------------------------------------------
[2018-10-17 02:14:44] phil at catalyst dot net dot nz
In the interim, here's a perl script which can be used to add this navigation to an existing
documentation set. You can apply it to the php-chunked-xhtml directory like so:
$ find php-chunked-xhtml/ -name "*.html" -print \
| xargs ./addnavlinks.pl
(assuming the following script is named "addnavlinks.pl" and is executable.)
#!/usr/bin/perl -pi
BEGIN{undef $/;}
s| </head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev"[^>]*><a
href="(.*?)">(.*?)</a></div>
<div class="next"[^>]*><a
href="(.*?)">(.*?)</a></div>
<div class="up"><a href="(.*?)">(.*?)</a></div>
<div class="home"><a href="(.*?)">(.*?)</a></div>
| <link rel="prev" href="\1" title="\2">
<link rel="next" href="\3" title="\4">
<link rel="up" href="\5" title="\6">
<link rel="home" href="\7" title="\8">
$&|
------------------------------------------------------------------------
[2018-10-16 01:55:24] phil at catalyst dot net dot nz
Description:
------------
Certain web browsers can utilise navigation metadata to make life easier for the user. By providing
'link' elements in the HTML 'head' with 'rel' attributes for the
"next", "prev", "up", and "start" pages, users of these
browsers can easily skip around the documentation.
Even better, some browsers can use this metadata to let the user interactively search throughout the
documentation, taking the user to the next page in the sequence containing a match (by following the
"next" links until a page containing a match is arrived at). The web browser built into
Emacs is one such example.
When using the offline documentation, this search ability can be incredibly useful, due to its sheer
convenience for the user, in combination with the speed of offline access.
It would be fantastic if the documentation contained these navigation link elements. Especially in
the downloadable archives (e.g. php_manual_en.tar.gz), as the aforementioned searching is fast for
local files.
Note that this same data is already being established and generated as the .manualnavbar div at the
top of the page, so I believe this feature request is just to add an additional rendering of that
data, which is hopefully quite straightforward to implement.
The following is an example for the "Variables" section landing page
language.variables.html:
<head>
<link rel="prev" title="Type Juggling"
href="language.types.type-juggling.html">
<link rel="next" title="Basics"
href="language.variables.basics.html">
<link rel="up" title="Language Reference" href="langref.html">
<link rel="start" title="PHP Manual" href="index.html">
</head>
Which is analogous to the following markup included in the <body>:
<div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a
href="language.types.type-juggling.html">Type Juggling</a></div>
<div class="next" style="text-align: right; float: right;"><a
href="language.variables.basics.html">Basics</a></div>
<div class="up"><a href="langref.html">Language
Reference</a></div>
<div class="home"><a href="index.html">PHP
Manual</a></div>
</div>
------------------------------------------------------------------------
--
Edit this bug report at https://bugs.php.net/bug.php?id=77018&edit=1