discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Links into HTML page would be great
@ 2017-02-28 14:33 Thomas Güttler
  2017-03-12 18:08 ` Ingo Schwarze
  0 siblings, 1 reply; 11+ messages in thread
From: Thomas Güttler @ 2017-02-28 14:33 UTC (permalink / raw)
  To: discuss

Hi,

it would be great if you could create a link which points to this:


   http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval

Unfortunately the "#ServerAliveInterval" part does not work. You can only create
a link to the man-page, not "ServerAliveInterval".

the matching nroff source is here:

   https://github.com/openbsd/src/blob/master/usr.bin/ssh/ssh_config.5#L1473

I think a lot of HTML versions of man pages would benefit, if you could
create pointing to "ssh_config.5#ServerAliveInterval"

Of course above is just an example. This should work for all man pages, not for
ssh_config only.

My background: I see a lot of answers at the Q+A site serverfault.com where
the user copy+pastes snippets from man pages.

It would be much better if you could create a link to the matching definition.

Here is the nroff snippet:

{{{
.It Cm ServerAliveInterval
Sets a timeout interval in seconds after which if no data has been received
from the server,
....
}}}

I have no clue how nroff works. I guess it is not easy to implement.

What do you think?

Regards,
   Thomas Güttler


-- 
Thomas Guettler http://www.thomas-guettler.de/
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-02-28 14:33 Links into HTML page would be great Thomas Güttler
@ 2017-03-12 18:08 ` Ingo Schwarze
  2017-03-12 19:39   ` Ingo Schwarze
  0 siblings, 1 reply; 11+ messages in thread
From: Ingo Schwarze @ 2017-03-12 18:08 UTC (permalink / raw)
  To: Thomas Guettler; +Cc: discuss

Hi Thomas,

Thomas Guettler wrote on Tue, Feb 28, 2017 at 03:33:00PM +0100:

> it would be great if you could create a link which points to this:
> http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval

You have a point.

> I have no clue how nroff works. I guess it is not easy to implement.

You may be wrong, it is likely not difficult.

For terminal output mode, i have already done it.
To see that, from the shell prompt,

 - type "man ssh_config" and press <ENTER>
 - then type ":tServerAliveInterval" and press <ENTER> again

Besides, note that

  http://man.openbsd.org/ssh_config#TOKENS

already works.

> What do you think?

I'll give it a shot.
It is likely to take a few days of coding at most, maybe less.
I may not be working on it without interruption, so it might
take a bit longer for the feature to be completed.

Thanks for the suggestion,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-03-12 18:08 ` Ingo Schwarze
@ 2017-03-12 19:39   ` Ingo Schwarze
  2017-03-13  9:42     ` Thomas Güttler
  0 siblings, 1 reply; 11+ messages in thread
From: Ingo Schwarze @ 2017-03-12 19:39 UTC (permalink / raw)
  To: Thomas Guettler, discuss

Hi,

Ingo Schwarze wrote on Sun, Mar 12, 2017 at 07:08:32PM +0100:
> Thomas Guettler wrote on Tue, Feb 28, 2017 at 03:33:00PM +0100:

>> it would be great if you could create a link which points to this:
>> http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval

> You have a point.
 
>> I have no clue how nroff works. I guess it is not easy to implement.

> You may be wrong, it is likely not difficult.

It turns out to be even easier than i anticipated.

Here is a proof-of-concept patch that i just installed on man.openbsd.org.
For now, it only does .Cm, merely because that's what Thomas used as
his example, and also because it is one of the macros where this is
useful.

If people speak up here who like that, or if i come to the
conclusion that i like it myself (which seems likely),
i will probably add support for some more macros, probably
.Ev .Fl .Ic .Ms .Dv .Li .No .Er .Sy .Em ,
do some polishing (for example making sure the tag contains no
invalid characters), then commit it in a few days.

The two macros .Fn and .Fd are slightly more tricky and may need
a bit of deliberation, but are probably feasible, too.

At first, i was a bit worried because what exactly such a tagging
facility will tag may not be completely stable over time.  But then
it occurred to me that really isn't a big deal.  I mean, even if
some external deep links sometimes go dead due to algorithmic changes,
we are not worse off than right now.  Even if those links are never
updated, they still point to the right page, only to the beginning
of it.

Yours,
  Ingo


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	12 Mar 2017 19:23:54 -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,7 @@ mdoc_fl_pre(MDOC_ARGS)
 static int
 mdoc_cm_pre(MDOC_ARGS)
 {
-	print_otag(h, TAG_B, "c", "Cm");
+	print_otag(h, TAG_B, "ci", "Cm", cond_id(n));
 	return 1;
 }
 
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-03-12 19:39   ` Ingo Schwarze
@ 2017-03-13  9:42     ` Thomas Güttler
  2017-03-13  9:56       ` Jan Stary
                         ` (2 more replies)
  0 siblings, 3 replies; 11+ messages in thread
From: Thomas Güttler @ 2017-03-13  9:42 UTC (permalink / raw)
  To: discuss, schwarze

Wow, this link works now - great :-)

http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval

Sometimes it is like paradise. You just need to speak out your whish.

Thank you!


Am 12.03.2017 um 20:39 schrieb Ingo Schwarze:
> Hi,
>
> Ingo Schwarze wrote on Sun, Mar 12, 2017 at 07:08:32PM +0100:
>> Thomas Guettler wrote on Tue, Feb 28, 2017 at 03:33:00PM +0100:
>
>>> it would be great if you could create a link which points to this:
>>> http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval
>
>> You have a point.
>
>>> I have no clue how nroff works. I guess it is not easy to implement.
>
>> You may be wrong, it is likely not difficult.
>
> It turns out to be even easier than i anticipated.
>
> Here is a proof-of-concept patch that i just installed on man.openbsd.org.
> For now, it only does .Cm, merely because that's what Thomas used as
> his example, and also because it is one of the macros where this is
> useful.
>
> If people speak up here who like that, or if i come to the
> conclusion that i like it myself (which seems likely),
> i will probably add support for some more macros, probably
> .Ev .Fl .Ic .Ms .Dv .Li .No .Er .Sy .Em ,
> do some polishing (for example making sure the tag contains no
> invalid characters), then commit it in a few days.
>
> The two macros .Fn and .Fd are slightly more tricky and may need
> a bit of deliberation, but are probably feasible, too.
>
> At first, i was a bit worried because what exactly such a tagging
> facility will tag may not be completely stable over time.  But then
> it occurred to me that really isn't a big deal.  I mean, even if
> some external deep links sometimes go dead due to algorithmic changes,
> we are not worse off than right now.  Even if those links are never
> updated, they still point to the right page, only to the beginning
> of it.
>
> Yours,
>   Ingo
>
>
> 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	12 Mar 2017 19:23:54 -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,7 @@ mdoc_fl_pre(MDOC_ARGS)
>  static int
>  mdoc_cm_pre(MDOC_ARGS)
>  {
> -	print_otag(h, TAG_B, "c", "Cm");
> +	print_otag(h, TAG_B, "ci", "Cm", cond_id(n));
>  	return 1;
>  }
>
> --
>  To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
>

-- 
Thomas Guettler http://www.thomas-guettler.de/
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  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-13  9:59       ` Thomas Güttler
  2017-03-13 21:35       ` Ingo Schwarze
  2 siblings, 2 replies; 11+ messages in thread
From: Jan Stary @ 2017-03-13  9:56 UTC (permalink / raw)
  To: discuss

On Mar 13 10:42:08, guettliml@thomas-guettler.de wrote:
> http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval

Thank you Ingo!

Anyway, in my firefox,
http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5
displays the synopsis as

SYNOPSIS
  ~/.ssh
  /config 	

  /etc/ssh
  /ssh_config 	


Only after I make the font smaller than 100% (with Crtrl + -) it becomes

SYNOPSIS
  ~/.ssh/config 	
  /etc/ssh/ssh_config

Why is that? Could it be besause of the hardwired width?
(Or is it a firefox bug to not recompute the relative widths (ex)?)

<h1 class="Sh" id="SYNOPSIS">SYNOPSIS</h1>
<table class="Nm">
  <colgroup>
    <col style="width: 13.00ex;"/>
    <col/>
  </colgroup>
  <tr>
    <td><b class="Nm">~/.ssh/config</b></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <colgroup>
    <col style="width: 19.00ex;"/>
    <col/>
  </colgroup>
  <tr>
    <td><b class="Nm">/etc/ssh/ssh_config</b></td>
    <td></td>
  </tr>
</table>

In lynx it displays fine.

	Jan

> 
> Am 12.03.2017 um 20:39 schrieb Ingo Schwarze:
> > Hi,
> > 
> > Ingo Schwarze wrote on Sun, Mar 12, 2017 at 07:08:32PM +0100:
> > > Thomas Guettler wrote on Tue, Feb 28, 2017 at 03:33:00PM +0100:
> > 
> > > > it would be great if you could create a link which points to this:
> > > > http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval
> > 
> > > You have a point.
> > 
> > > > I have no clue how nroff works. I guess it is not easy to implement.
> > 
> > > You may be wrong, it is likely not difficult.
> > 
> > It turns out to be even easier than i anticipated.
> > 
> > Here is a proof-of-concept patch that i just installed on man.openbsd.org.
> > For now, it only does .Cm, merely because that's what Thomas used as
> > his example, and also because it is one of the macros where this is
> > useful.
> > 
> > If people speak up here who like that, or if i come to the
> > conclusion that i like it myself (which seems likely),
> > i will probably add support for some more macros, probably
> > .Ev .Fl .Ic .Ms .Dv .Li .No .Er .Sy .Em ,
> > do some polishing (for example making sure the tag contains no
> > invalid characters), then commit it in a few days.
> > 
> > The two macros .Fn and .Fd are slightly more tricky and may need
> > a bit of deliberation, but are probably feasible, too.
> > 
> > At first, i was a bit worried because what exactly such a tagging
> > facility will tag may not be completely stable over time.  But then
> > it occurred to me that really isn't a big deal.  I mean, even if
> > some external deep links sometimes go dead due to algorithmic changes,
> > we are not worse off than right now.  Even if those links are never
> > updated, they still point to the right page, only to the beginning
> > of it.
> > 
> > Yours,
> >   Ingo
> > 
> > 
> > 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	12 Mar 2017 19:23:54 -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,7 @@ mdoc_fl_pre(MDOC_ARGS)
> >  static int
> >  mdoc_cm_pre(MDOC_ARGS)
> >  {
> > -	print_otag(h, TAG_B, "c", "Cm");
> > +	print_otag(h, TAG_B, "ci", "Cm", cond_id(n));
> >  	return 1;
> >  }
> > 
> > --
> >  To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
> > 
> 
> -- 
> Thomas Guettler http://www.thomas-guettler.de/
> --
> To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
> 
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-03-13  9:42     ` Thomas Güttler
  2017-03-13  9:56       ` Jan Stary
@ 2017-03-13  9:59       ` Thomas Güttler
  2017-03-13 15:32         ` Ingo Schwarze
  2017-03-13 21:35       ` Ingo Schwarze
  2 siblings, 1 reply; 11+ messages in thread
From: Thomas Güttler @ 2017-03-13  9:59 UTC (permalink / raw)
  To: discuss, schwarze

I discovered, that this works for systemd man page, too:

https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type=

I am unsure, but I think this is new.

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

Thank you for your support.

Regards,
   Thomas

Am 13.03.2017 um 10:42 schrieb Thomas Güttler:
> Wow, this link works now - great :-)
>
> http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval
>
> Sometimes it is like paradise. You just need to speak out your whish.
>
> Thank you!
>
>
> Am 12.03.2017 um 20:39 schrieb Ingo Schwarze:
>> Hi,
>>
>> Ingo Schwarze wrote on Sun, Mar 12, 2017 at 07:08:32PM +0100:
>>> Thomas Guettler wrote on Tue, Feb 28, 2017 at 03:33:00PM +0100:
>>
>>>> it would be great if you could create a link which points to this:
>>>> http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#ServerAliveInterval
>>
>>> You have a point.
>>
>>>> I have no clue how nroff works. I guess it is not easy to implement.
>>
>>> You may be wrong, it is likely not difficult.
>>
>> It turns out to be even easier than i anticipated.
>>
>> Here is a proof-of-concept patch that i just installed on man.openbsd.org.
>> For now, it only does .Cm, merely because that's what Thomas used as
>> his example, and also because it is one of the macros where this is
>> useful.
>>
>> If people speak up here who like that, or if i come to the
>> conclusion that i like it myself (which seems likely),
>> i will probably add support for some more macros, probably
>> .Ev .Fl .Ic .Ms .Dv .Li .No .Er .Sy .Em ,
>> do some polishing (for example making sure the tag contains no
>> invalid characters), then commit it in a few days.
>>
>> The two macros .Fn and .Fd are slightly more tricky and may need
>> a bit of deliberation, but are probably feasible, too.
>>
>> At first, i was a bit worried because what exactly such a tagging
>> facility will tag may not be completely stable over time.  But then
>> it occurred to me that really isn't a big deal.  I mean, even if
>> some external deep links sometimes go dead due to algorithmic changes,
>> we are not worse off than right now.  Even if those links are never
>> updated, they still point to the right page, only to the beginning
>> of it.
>>
>> Yours,
>>   Ingo
>>
>>
>> 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    12 Mar 2017 19:23:54 -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,7 @@ mdoc_fl_pre(MDOC_ARGS)
>>  static int
>>  mdoc_cm_pre(MDOC_ARGS)
>>  {
>> -    print_otag(h, TAG_B, "c", "Cm");
>> +    print_otag(h, TAG_B, "ci", "Cm", cond_id(n));
>>      return 1;
>>  }
>>
>> --
>>  To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
>>
>

-- 
Thomas Guettler http://www.thomas-guettler.de/
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-03-13  9:59       ` Thomas Güttler
@ 2017-03-13 15:32         ` Ingo Schwarze
  0 siblings, 0 replies; 11+ messages in thread
From: Ingo Schwarze @ 2017-03-13 15:32 UTC (permalink / raw)
  To: Thomas Guettler; +Cc: discuss

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-03-13  9:42     ` Thomas Güttler
  2017-03-13  9:56       ` Jan Stary
  2017-03-13  9:59       ` Thomas Güttler
@ 2017-03-13 21:35       ` Ingo Schwarze
  2 siblings, 0 replies; 11+ messages in thread
From: Ingo Schwarze @ 2017-03-13 21:35 UTC (permalink / raw)
  To: discuss; +Cc: Thomas Güttler

Hi,

the feature suggested by Thomas is now implemented, committed,
and in production on man.openbsd.org, for example:

  http://man.openbsd.org/ssh_config.5#ServerAliveInterval

There are probably still some rough edges.  If you see anything
that is missing or could be improved, don't hesitate to speak up.

I'll look at Jan's observation regarding widths and line breaks later.

Yours,
  Ingo


CVSROOT:	/cvs
Module name:	src
Changes by:	schwarze@cvs.openbsd.org	2017/03/13 14:22:11

Modified files:
	usr.bin/mandoc : mandoc.css mdoc_html.c 

Log message:
Port ctags-style, less(1) :t internal searching from terminal output
to HTML output.  For certain macros appearing at the beginning of .It
heads, write HTML id="..." attributes such that deep linking works.
Write HTML <a> attributes such that you can easily copy out link
targets with the mouse.  Try: http://man.openbsd.org/vmctl.8#create

Feature suggested by <guettliml at Thomas dash Guettler dot de>,
some details of the design and implementation by me.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-03-13  9:56       ` Jan Stary
@ 2017-03-14  1:49         ` Ingo Schwarze
  2017-03-14  9:39         ` Jan Stary
  1 sibling, 0 replies; 11+ messages in thread
From: Ingo Schwarze @ 2017-03-14  1:49 UTC (permalink / raw)
  To: Jan Stary; +Cc: discuss

Hi Jan,

Jan Stary wrote on Mon, Mar 13, 2017 at 10:56:27AM +0100:

> Anyway, in my firefox,
> http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5
> displays the synopsis as
> 
> SYNOPSIS
>   ~/.ssh
>   /config 	
> 
>   /etc/ssh
>   /ssh_config 	
> 
> 
> Only after I make the font smaller than 100% (with Crtrl + -) it becomes
> 
> SYNOPSIS
>   ~/.ssh/config 	
>   /etc/ssh/ssh_config
> 
> Why is that? Could it be besause of the hardwired width?

Yes.

> (Or is it a firefox bug to not recompute the relative widths (ex)?)

No, it is a bug in mandoc, not in firefox.

> <h1 class="Sh" id="SYNOPSIS">SYNOPSIS</h1>
> <table class="Nm">
>   <colgroup>
>     <col style="width: 13.00ex;"/>

At this point, we still have "font-weight: normal;".
So the column width is (about) 13 normal-weight characters.

>     <col/>
>   </colgroup>
>   <tr>
>     <td><b class="Nm">~/.ssh/config</b></td>

But here, we print 13 bold characters.
They don't fit and get wrapped.

> In lynx it displays fine.

Yes, the above is generally no problem width fixed-width fonts.
In mandoc -Tascii and mandoc -Tutf8, it also works fine.

Similar issues might exist in PostScript and PDF, but i'll
treat that as a different story for now.

Thanks for mentioning this,
  Ingo


Log Message:
-----------
Slightly increase widths calculated from string lengths (mainly 
for .Bl -tag lists and SYNOPSIS .Nm blocks), such that the text
still fits even if it is printed in bold font.  
This is an ugly band aid - but implementing font-dependent width
measurements would be a major project and even more difficult 
for HTML than for PostScript.

Issue reported by Jan Stary <hans at stare dot cz>.

Modified Files:
--------------
    mdocml:
        html.c
        mdoc_html.c

Revision Data
-------------
Index: html.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/html.c,v
retrieving revision 1.208
retrieving revision 1.209
diff -Lhtml.c -Lhtml.c -u -p -r1.208 -r1.209
--- html.c
+++ html.c
@@ -591,6 +591,8 @@ print_otag(struct html *h, enum htmltag 
 				break;
 			su = &mysu;
 			a2width(arg2, su);
+			/* Increase width to make even bold text fit. */
+			su->scale *= 1.1;
 			if (fmt[-1] == 'W')
 				su->scale *= -1.0;
 			break;
Index: mdoc_html.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mdoc_html.c,v
retrieving revision 1.275
retrieving revision 1.276
diff -Lmdoc_html.c -Lmdoc_html.c -u -p -r1.275 -r1.276
--- mdoc_html.c
+++ mdoc_html.c
@@ -628,7 +628,8 @@ mdoc_nm_pre(MDOC_ARGS)
 		len = html_strlen(meta->name);
 
 	t = print_otag(h, TAG_COLGROUP, "");
-	print_otag(h, TAG_COL, "shw", len);
+	/* Increase width to make even bold text fit. */
+	print_otag(h, TAG_COL, "shw", len + 2);
 	print_otag(h, TAG_COL, "");
 	print_tagq(h, t);
 	print_otag(h, TAG_TR, "");
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  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
  1 sibling, 1 reply; 11+ messages in thread
From: Jan Stary @ 2017-03-14  9:39 UTC (permalink / raw)
  To: discuss

Hi Ingo,

in e.g.
http://man.openbsd.org/vmctl.8#create
the mouseover is "Cm", and it's "Fl" for the options,
and similarly for "Sx", "Xr" and the others.

  <dt class="It-tag" style="margin-left: -6.60ex;"><a class="selflink"
  href="#create"><b class="Cm" title="Cm" id="create">create</b></a>

That seems a bit odd to display. Is that intended?
I get why it's the class, but why is it the title?

	Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: Links into HTML page would be great
  2017-03-14  9:39         ` Jan Stary
@ 2017-03-14 17:17           ` Ingo Schwarze
  0 siblings, 0 replies; 11+ messages in thread
From: Ingo Schwarze @ 2017-03-14 17:17 UTC (permalink / raw)
  To: Jan Stary; +Cc: discuss

Hi Jan,

Jan Stary wrote on Tue, Mar 14, 2017 at 10:39:12AM +0100:

> in e.g.
> http://man.openbsd.org/vmctl.8#create
> the mouseover is "Cm", and it's "Fl" for the options,
> and similarly for "Sx", "Xr" and the others.
> 
>   <dt class="It-tag" style="margin-left: -6.60ex;"><a class="selflink"
>   href="#create"><b class="Cm" title="Cm" id="create">create</b></a>
> 
> That seems a bit odd to display.

What is odd about that?

> Is that intended?

Yes.

> I get why it's the class, but why is it the title?

Because semantic markup is the whole point of the mdoc(7) language,
and not communicating the semantics to the user is a shame and a waste?

For example, in a section 3 manual, italic font might mean a function
type, a variable type, a function argument, a variable name, a path
name, stress emphasis and so on...  Anywhere, typewriter font might
mean a preprocessor constant, an error constant, an environment
variable...  It is obviously useful to be able to distinguish these
possibilities without guessing, or isn't it?

Besides, you can search for these macros keys with apropos(1),
so getting familiar with them over time is very useful.

Besides, OpenBSD is a developer-oriented system.  We enncourage
users to improve the system and send patches.  Some become developers,
and there is no other way of becoming a developer.  Getting familiar
with the macros is not just useful to better understand the content,
and to use search facilities efficiently, but also to lower the
barrier for sending patches.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2017-03-14 17:17 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-02-28 14:33 Links into HTML page would be great 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
2017-03-13 21:35       ` Ingo Schwarze

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).