php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Request #77018 Generate 'link' elements in HTML head, for rel="next", "prev", "up", "start"
Submitted: 2018-10-16 01:55 UTC Modified: 2018-10-17 03:00 UTC
From: phil at catalyst dot net dot nz Assigned:
Status: Open Package: Doc Build problem
PHP Version: master-Git-2018-10-16 (Git) OS:
Private report: No CVE-ID: None
Welcome back! If you're the original bug submitter, here's where you can edit the bug or add additional notes.
If you forgot your password, you can retrieve your password here.
Password:
Status:
Package:
Bug Type:
Summary:
From: phil at catalyst dot net dot nz
New email:
PHP Version: OS:

 

 [2018-10-16 01:55 UTC] 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>



Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2018-10-17 02:14 UTC] 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-17 03:00 UTC] phil at catalyst dot net dot nz
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.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Fri Oct 04 19:01:27 2024 UTC