discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Thomas Guettler <guettliml@thomas-guettler.de>
Cc: discuss@mdocml.bsd.lv
Subject: Re: Links into HTML page would be great
Date: Mon, 13 Mar 2017 16:32:38 +0100	[thread overview]
Message-ID: <20170313153238.GA33078@athene.usta.de> (raw)
In-Reply-To: <52d83eb6-052a-0f71-5c01-650956753c76@thomas-guettler.de>

Hi Thomas,

Thomas Guettler wrote on Mon, Mar 13, 2017 at 10:59:24AM +0100:

> I discovered, that this works for systemd man page, too:
> https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type=

That page is written in a completely different language and formatted
by completely different technology.  Near the top, you see:

  <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">

So this not a proper manual page, but generated from DocBook input.

Overall, this results in lower-quality HTML:

  https://validator.w3.org/check?uri=https%3A%2F%2Fwww.freedesktop.org%2Fsoftware%2Fsystemd%2Fman%2Fsystemd.service.html

It does not even have a valid <!DOCTYPE>.

Besides, while it does have some id= attributes, they appear sparsely,
and most contain HTML syntax errors.

> I am unsure, but I think this is new.

I have no idea.  DocBook is not really worth wasting time on.
It is low-quality corporate bloatware.

> The above systemd page makes it easy for you to create a link
> inclusive "#....".  If you click on this sign 6, then your browser
> gets pointed to this part in the page.... nice.

That's an interesting idea, but the implementation is rather ugly.

  You see this HTML code:

    <dt id="Type=">
      <span class="term">
        <code class="varname">Type=</code>
      </span>
      <a class="headerlink" title="Permalink to this term"
         href="#Type=">&#00B6;</a>
    </dt>

  together with this this embedded CSS (shortened deleting useless
  attributes):

    a.headerlink { visibility: hidden; }
    dt:hover > a.headerlink { visibility: visible; }

At the very least, the CSS could be moved to the main stylesheet,
it is not document-specific.

You do not see that anything is special about the word before you
hover over it, and if you do, the text appearing inline may mess up
the right margin.

It would probably be better to simply wrap the .Cm element in
an <a> element pointing to the .Cm element itself.  See below
for a simple implementation, also installed on man.openbsd.org
such that you can see it in action: You see that there is something
special about the .Cm right away because of the dotted bottom border,
so maybe you become curious and hover, and then you see the link
and can copy it, but without any change in the displayed text.

I think now i know how to implement all this.
Off to the workbench...

Thanks again,
  Ingo


Index: mandoc.css
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.css,v
retrieving revision 1.4
diff -u -p -r1.4 mandoc.css
--- mandoc.css	5 Feb 2017 21:00:18 -0000	1.4
+++ mandoc.css	13 Mar 2017 15:15:47 -0000
@@ -14,6 +14,11 @@ ul, ol, dl {	margin-top: 0em;
 		margin-bottom: 0em; }
 li, dt {	margin-top: 1em; }
 
+a.selflink {	color: inherit;
+		font: inherit;
+		text-decoration: inherit;
+		border-bottom: thin dotted; }
+
 /* Search form and search results. */
 
 fieldset {	border: thin solid silver;
Index: mdoc_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_html.c,v
retrieving revision 1.148
diff -u -p -r1.148 mdoc_html.c
--- mdoc_html.c	3 Mar 2017 13:55:06 -0000	1.148
+++ mdoc_html.c	13 Mar 2017 15:15:47 -0000
@@ -46,6 +46,7 @@ struct	htmlmdoc {
 	void		(*post)(MDOC_ARGS);
 };
 
+static	const char	 *cond_id(const struct roff_node *);
 static	char		 *make_id(const struct roff_node *);
 static	void		  print_mdoc_head(MDOC_ARGS);
 static	void		  print_mdoc_node(MDOC_ARGS);
@@ -496,6 +497,22 @@ make_id(const struct roff_node *n)
 	return buf;
 }
 
+static const char *
+cond_id(const struct roff_node *n)
+{
+	if (n->child != NULL &&
+	    n->child->type == ROFFT_TEXT &&
+	    (n->prev == NULL ||
+	     (n->prev->type == ROFFT_TEXT &&
+	      strcmp(n->prev->string, "|") == 0)) &&
+	    (n->parent->tok == MDOC_It ||
+	     (n->parent->tok == MDOC_Xo &&
+	      n->parent->parent->prev == NULL &&
+	      n->parent->parent->parent->tok == MDOC_It)))
+		return n->child->string;
+	return NULL;
+}
+
 static int
 mdoc_sh_pre(MDOC_ARGS)
 {
@@ -549,7 +566,12 @@ mdoc_fl_pre(MDOC_ARGS)
 static int
 mdoc_cm_pre(MDOC_ARGS)
 {
-	print_otag(h, TAG_B, "c", "Cm");
+	const char	*id;
+
+	id = cond_id(n);
+	if (id != NULL)
+		print_otag(h, TAG_A, "chR", "selflink", id);
+	print_otag(h, TAG_B, "ci", "Cm", id);
 	return 1;
 }
 
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

  reply	other threads:[~2017-03-13 15:32 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-02-28 14:33 Thomas Güttler
2017-03-12 18:08 ` Ingo Schwarze
2017-03-12 19:39   ` Ingo Schwarze
2017-03-13  9:42     ` Thomas Güttler
2017-03-13  9:56       ` Jan Stary
2017-03-14  1:49         ` Ingo Schwarze
2017-03-14  9:39         ` Jan Stary
2017-03-14 17:17           ` Ingo Schwarze
2017-03-13  9:59       ` Thomas Güttler
2017-03-13 15:32         ` Ingo Schwarze [this message]
2017-03-13 21:35       ` Ingo Schwarze

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170313153238.GA33078@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mdocml.bsd.lv \
    --cc=guettliml@thomas-guettler.de \
    --subject='Re: Links into HTML page would be great' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).