Minimal support for <LINK REL="next"> etc machine-readable navigation links.

Off by default for now, but I don't intend that it should stay this way; they
seem useful and harmless. I just want to check a few more browsers to ensure
they don't do anything obnoxious with them.

So far I've only seen lynx and links do something with them (provide toolbars).
iCab and some Mozilla derivatives/extensions are also alleged to do this; Opera
is said to allow PgDn type browsing through the entire set of pages; and
Mozilla is rumoured to use the "next" link for prefetching.

git-svn-id: svn://svn.tartarus.org/sgt/halibut@7177 cda61777-01e9-0310-a592-d414129be87e

diff --git a/bk_html.c b/bk_html.c
index dcfbcb7..500afcf 100644 (file)
--- a/bk_html.c
+++ b/bk_html.c
@@ -49,6 +49,7 @@ typedef struct {
     int address_section, visible_version_id;
     int leaf_contains_contents, leaf_smallest_contents;
     int navlinks;
+    int rellinks;
     char *contents_filename;
     char *index_filename;
     char *template_filename;
@@ -259,6 +260,7 @@ static htmlconfig html_configure(paragraph *source) {
     ret.leaf_contains_contents = FALSE;
     ret.leaf_smallest_contents = 4;
     ret.navlinks = TRUE;
+    ret.rellinks = FALSE;
     ret.single_filename = dupstr("Manual.html");
     ret.contents_filename = dupstr("Contents.html");
     ret.index_filename = dupstr("IndexPage.html");
@@ -381,6 +383,8 @@ static htmlconfig html_configure(paragraph *source) {
                ret.achapter.just_numbers = utob(uadv(k));
            } else if (!ustricmp(k, L"html-suppress-navlinks")) {
                ret.navlinks = !utob(uadv(k));
+           } else if (!ustricmp(k, L"html-rellinks")) {
+               ret.rellinks = utob(uadv(k));
            } else if (!ustricmp(k, L"html-chapter-suffix")) {
                ret.achapter.number_suffix = uadv(k);
            } else if (!ustricmp(k, L"html-leaf-level")) {
@@ -957,6 +961,40 @@ void html_backend(paragraph *sourceform, keywordlist *keywords,
            element_close(&ho, "title");
            html_nl(&ho);
 
+           if (conf.rellinks) {
+
+               if (prevf) {
+                   element_empty(&ho, "link");
+                   element_attr(&ho, "rel", "previous");
+                   element_attr(&ho, "href", prevf->filename);
+                   html_nl(&ho);
+               }
+
+               /* FIXME: link rel="up" */
+
+               if (f != files.head) {
+                   element_empty(&ho, "link");
+                   element_attr(&ho, "rel", "ToC");
+                   element_attr(&ho, "href", files.head->filename);
+                   html_nl(&ho);
+               }
+
+               if (has_index && files.index && f != files.index) {
+                   element_empty(&ho, "link");
+                   element_attr(&ho, "rel", "index");
+                   element_attr(&ho, "href", files.index->filename);
+                   html_nl(&ho);
+               }
+
+               if (f->next) {
+                   element_empty(&ho, "link");
+                   element_attr(&ho, "rel", "next");
+                   element_attr(&ho, "href", f->next->filename);
+                   html_nl(&ho);
+               }
+
+           }
+
            if (conf.head_end)
                html_raw(&ho, conf.head_end);
 

diff --git a/doc/index.but b/doc/index.but
index b8587c7..e9d6e51 100644 (file)
--- a/doc/index.but
+++ b/doc/index.but
@@ -337,6 +337,9 @@ configuration directive
 \IM{\\cfg\{html-suppress-navlinks\}}
 \cw{\\cfg\{html-suppress-navlinks\}}
 
+\IM{\\cfg\{html-rellinks\}} \c{html-rellinks} configuration directive
+\IM{\\cfg\{html-rellinks\}} \cw{\\cfg\{html-rellinks\}}
+
 \IM{\\cfg\{html-author\}} \c{html-author} configuration directive
 \IM{\\cfg\{html-author\}} \cw{\\cfg\{html-author\}}
 

diff --git a/doc/output.but b/doc/output.but
index 001a03a..67827fc 100644 (file)
--- a/doc/output.but
+++ b/doc/output.but
@@ -769,10 +769,32 @@ visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
 file. If it is set to \c{false}, they will only be included as HTML
 comments.
 
+\dt \I{\cw{\\cfg\{html-rellinks\}}}\cw{\\cfg\{html-rellinks\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{true}, machine-readable relational links will
+be emitted in each HTML file (\I{\cw{<LINK>} tags}\cw{<LINK
+REL="}\e{next}\cw{">} and so on within the \i\cw{<HEAD>} section)
+providing links to related files. The same set of links are provided
+as in the navigation bar (with which this should not be confused).
+
+\lcont{
+
+Some browsers make use of this semantic information, for instance to
+allow easy navigation through related pages, and to prefetch the next
+page. However, many browsers ignore this markup, so it would be unwise
+to rely on it for navigation.
+
+The use and rendering of this information is entirely up to the
+browser; none of the other Halibut options for the navigation bar will
+have any effect.
+
+}
+
 \dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}}
 
-\dd If this is set to \c{true}, the usual \i{navigation links} at the
-top of each HTML file will be suppressed.
+\dd If this is set to \c{true}, the usual \i{navigation links} within
+the \e{body} of each HTML file (near the top of the rendered page) will
+be suppressed.
 
 \dt \I{\cw{\\cfg\{html-suppress-address\}}}\cw{\\cfg\{html-suppress-address\}\{}\e{boolean}\cw{\}}
 
@@ -951,6 +973,8 @@ The \i{default settings} for Halibut's HTML output format are:
 \c \cfg{html-version}{html4}
 \c \cfg{html-template-fragment}{%b}
 \c \cfg{html-versionid}{true}
+\c \cfg{html-include-rellinks}{false}
+\c \cfg{html-suppress-navlinks{false}
 \c \cfg{html-suppress-address}{false}
 \c \cfg{html-author}{}
 \c \cfg{html-description}{}