discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Jackson Pauls <jacksonpauls@gmail.com>
To: discuss@mandoc.bsd.lv
Subject: mandoc HTML output: minor issues
Date: Fri, 25 Aug 2017 10:52:58 +0100	[thread overview]
Message-ID: <CAM9P35sU4hTE7LTvhU91TvRLAgD+BSksPchDSkJt+61yw0E_Lg@mail.gmail.com> (raw)

Hi,

I use mandoc 1.14.3 to generate HTML from mdoc sources. I've noticed a
few issues with the HTML output, in no particular order:


1. Duplicate IDs (invalid HTML). E.g. dash.1 gets two elements with
id="HISTSIZE":
...
1138       <dt class="It-tag" style="margin-left: -12.60ex;"><a
class="selflink" href="#HISTSIZE"><code class="Ev" title="Ev"
id="HISTSIZE">HISTSIZE</code></a></dt>
...
1921   <dt class="It-tag" style="margin-left: -13.80ex;"><a
class="selflink" href="#HISTSIZE"><code class="Ev" title="Ev"
id="HISTSIZE">HISTSIZE</code></a></dt>
...
(1138 and 1921 are the line numbers as per my version.)


2. Broken in-page links. E.g. in dash.1, there is an <h2> with
id="White_Space_Splitting_(Field_Splitting)", but the link to that
heading is missing the bit in parentheses
(href="#White_Space_Splitting"):
...
 867 <h2 class="Ss" title="Ss"
id="White_Space_Splitting_(Field_Splitting)"><a class="selflink"
href="#White_Space_Splitting_(Field_Splitting)">White
 868   Space Splitting (Field Splitting)</a></h2>
...
1915       See the <a class="Sx" title="Sx"
href="#White_Space_Splitting">White Space
1916       Splitting</a> section for more details.</dd>
...

Perhaps this is an issue with the mdoc source, but maybe links
shouldn't be created in this case:
...
1014 .Ss White Space Splitting (Field Splitting)
...
2300 .Sx White Space Splitting
...


3. In babel.1, for the -: flag, the colon appears outside the .Fl element:
...
 63       <b class="Fl" title="Fl">-</b>:
...

I expected: <b class="Fl" title="Fl">-:</b>

mdoc source line:
...
 21 .Op Fl i Ar input-type | Fl : Qo Ar SMILES-string Qc
...


4. Running v.Nu (https://validator.github.io/validator/) on a
collection of HTML files generated by mandoc picks up duplicate IDs,
and a bunch of other issues:
* unescaped characters in href attributes (%, "),
* unescaped characters in URL fragments (\, {, }, #, ^, [, ], <, |),
* <div>s appearing inside <pre>s, and
* mismatches between column count in <colgroup> and table rows.
I can gather a bunch of examples if of interest.


5. Finally, I see mandoc adds today's date to the footer if it can't
parse one from the source file. I think this can be misleading, making
it appear a man page has been updated more recently than it actually
has. It would be nice to have an option to disable this behaviour, and
output an empty string or "UNDATED" instead.


mandoc is a pleasure to use btw, I hope the above is useful.


Cheers, Jackson

www.mankier.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

             reply	other threads:[~2017-08-25  9:53 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-08-25  9:52 Jackson Pauls [this message]
2017-08-29  8:47 ` Anthony J. Bentley
2017-08-29 15:56   ` Jackson Pauls

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=CAM9P35sU4hTE7LTvhU91TvRLAgD+BSksPchDSkJt+61yw0E_Lg@mail.gmail.com \
    --to=jacksonpauls@gmail.com \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: mandoc HTML output: minor issues' \
    /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).