From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wm1-f66.google.com (mail-wm1-f66.google.com [209.85.128.66]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id c19b1198 for ; Wed, 24 Oct 2018 03:03:25 -0500 (EST) Received: by mail-wm1-f66.google.com with SMTP id r63-v6so4330177wma.4 for ; Wed, 24 Oct 2018 01:03:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:content-transfer-encoding:in-reply-to :user-agent; bh=cm445jzHYDUyGZECSWeGeLlW2qpEH35HnjxtDZTxN6Q=; b=fqJdkmVmmx44QHBeIS7oqdz3rAbvh7wKFOHBgoXGnui/1Wt75dvOZK445bzNW9xW6a K7GpXRqt4gyDm7RhwDHb7OO7EfCiQ3jU5oJp54lhLfbETnvBxQSe5h8icv/MIDeVJMTi qTv3nOwhg59dLDIOhb2K46hbfWZ6ddf+duTG0x9C1P7LsSTTHqXe0HEKmD08HJU3dSgK qyxCUyG5St1jkA0OlyivzM6onvR0ylQK8VfiQCj7WrPcMGxuLtgs9KuOOe+mV4r57xZ6 jyivSLUGqwk6gXrv+oK6a3muUDsEQ5GKOWzhdEyGeIe/YbIWcsECxjxYF81dV0FFEH4d p4dw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:content-transfer-encoding :in-reply-to:user-agent; bh=cm445jzHYDUyGZECSWeGeLlW2qpEH35HnjxtDZTxN6Q=; b=kBCckQIxM6hX58wipXikY6oHlQK/88yJMHzLOJYl3rb3kW0a+gX6sLLC01CMMmAhFO 7VdHXBZ3TddIjIGtaIOGJBaYV7wrmeIvKXJB71s4v0sq1bN0gOvnPFqcw05wRvy2MM5A uwfxtduqP1mXZIQKO6xtpfNMv7HFP8/G1rOxFRazxxuY52hfECapoozh9eFm3vz+cyF+ aVVNysqtxCrU1kwxMZvZp1z+rldLBi7GQyPe83xMuLDDD8gBp1L1VYKSvrrOcKDilPWA EcgnfjGLuTK6LZtj3QIUPDoAxWdoXB8m0k/1TwoG58mCkdoXNcYLkxQ3/bf57sdCIPE2 ZZLw== X-Gm-Message-State: AGRZ1gJwAzl/O2JKuRov7E2X6FyGk4mG9fkJzNOVTwIBijHSQDDkBosY tVIPVSCAiKJ+lgn5t1zwYjU= X-Google-Smtp-Source: AJdET5dz+PBjou9cPEpSO4vkGS9HdziIyyiY27B0YhA6JMaw+2GnPaG8/gzwNRCTqwbqkwkGKUzTQQ== X-Received: by 2002:a1c:1dc8:: with SMTP id d191-v6mr1476594wmd.27.1540368203768; Wed, 24 Oct 2018 01:03:23 -0700 (PDT) Received: from pali ([2a02:2b88:2:1::5cc6:2f]) by smtp.gmail.com with ESMTPSA id z185-v6sm6407456wmz.47.2018.10.24.01.03.22 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 24 Oct 2018 01:03:23 -0700 (PDT) Date: Wed, 24 Oct 2018 10:03:22 +0200 From: Pali =?utf-8?B?Um9ow6Fy?= To: Ingo Schwarze Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181024080322.hc6ifwgydpccjif3@pali> References: <20180913151226.oaon3nvlvgcqioau@pali> <20181011075247.2jo4of7bkpvhkekm@pali> <20181023174545.GD58247@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20181023174545.GD58247@athene.usta.de> User-Agent: NeoMutt/20170113 (1.7.2) On Tuesday 23 October 2018 19:45:45 Ingo Schwarze wrote: > Hi Pali, > > Pali Rohar wrote on Thu, Oct 11, 2018 at 09:52:47AM +0200: > > On Thursday 13 September 2018 17:12:26 Pali Rohar wrote: > > >> In perl world is documentation for perl modules or perl scripts writing > >> in the POD format. Build process for perl scripts/modules then convert > >> POD documentation into manpages and install it into standard system > >> location. > >> > >> I looked at Debian manpages which uses mandoc for converting man pages > >> to HTML and basically documentation for perl modules is not good. > >> > >> For example this is HTMLized manpage for Email::Address::XS perl module: > >> https://manpages.debian.org/Email::Address::XS > >> > >> There is also converting tool which formats POD documentation directly > >> into HTML output. And for Email::Address::XS module is looks like: > >> https://metacpan.org/pod/Email::Address::XS > >> > >> So, I would like to ask, how can be HTML output generated from perl > >> manpages improved (process: POD --> mandoc --> HTML), so documentation > >> would be more close to the native HTML output (process: POD --> HTML)? > >> > >> I understand that something like syntax highlighting is not possible, > >> but if you look at differences, in HTML output from mandoc are broken > >> vertical spaces (some are totally missing) > > At first, i got confused because your report isn't really related > to the POD format at all (but your mail misled me to think so), > because your English is slightly hard to understand, because the > actual bug you were trying to report was well hidden near the end > of the text, because you only vaguely alluded to what was wrong with > the output without being specific, and because i couldn't readily > access the actual source document you were trying to format - and > then i forgot about the report. Sorry for the delay! Hi Ingo! Sorry for that. English is not my native language and I guessed that problem could be in Pod::Man... > >> or missing all different font families. > > I'm still not sure what you are alluding to here - can you be more > specific? Different font families. E.g. directive C<...> in POD switches font family to typewriter/monospaced, I<...> to italic, B<...> to bold... Looks like that bold and italic families are working. But typewriter/monospaced font is somehow ignored or unsupported in html output from mandoc. If you look at the output for Email::Address::XS, then whole SYNOPSIS should be written in typewriter/monospaced font. Or e.g. section "Deprecated Functions and Variables" has also some keywords in monospaced font and remaining parts are in normal/roman font. Compare it with html output on metacpan to see how it should look like. > >> If problem is in POD --> manpage converter (Pod::Man module), I can > >> look at it. > > In general, that is not very likely. Pod2man is very stable software > that rarely changes nowadays, and i hardly ever found a bug in it - > well, maybe one in a decade or so. > > Besides, even if pod2man(1) would contain a bug, mandoc(1) should > possibly try to cope because pod2man(1) is so stable and widespread > that whatever it does can almost be considered a feature. Ok. But seems that Pod::Man is still under development and fixes bugs... https://metacpan.org/changes/distribution/podlators > >> But at the first I would need to know what mandoc is able to > >> process and what not. > > Most of that is documented in the man(7) and roff(7) manual pages > included in the mandoc distribution. To explain more details, i > would need a more specific question - which feature is it that > you feel unsure whether mandoc implements it or not? > > Besides, (new) manual pages should really only use a tiny fraction > of the features implemented in mandoc. Most of the functionality > is provided purely fo backward compatibility. > > > Just to note, raw manpage (generated by Pod::Man) is available there: > > https://manpages.debian.org/Email::Address::XS.3pm.en.gz > > Oh yes, that link is helpful, and thanks for the reminder. Btw, link to raw manpage is also in the upper right corner of HTMLized Debian page. > > And viewing it on terminal does not case problems with vertical spaces > > like in HTML output. > > > > So it is problem in mandoc HTML generator? > > Yes, in the mandoc -man -Thtml formatter; i fixed it with the > commit appended below. Great, thank you! > In general, finding problems in -man -Thtml output is still more > likely than in -mdoc -Thtml because the man(7) language is much > more complicated than mdoc(7), much less suited to translation to > HTML because it is purely presentational, and much less used in > practice, so mostly untested. > > Thanks for the report and sorry again for the delay, > Ingo > > > Log Message: > ----------- > Input lines that are not blank but generate no output, > for example lines containing nothing but "\&", are significant > in no-fill mode and can be represented by blank lines inside 
.
> Fixing a bug that Pali dot Rohar at gmail dot com found
> in pod2man(1) output, for example Email::Address::XS(3p).
> 
> While here, inside no-fill mode, there is no need to encode
> totally blank input lines by emulating .PP - just let them
> through as we are inside 
 anyway.
> 
> Modified Files:
> --------------
>     mandoc:
>         man_html.c
> 
> Revision Data
> -------------
> Index: man_html.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
> retrieving revision 1.156
> retrieving revision 1.157
> diff -Lman_html.c -Lman_html.c -u -p -r1.156 -r1.157
> --- man_html.c
> +++ man_html.c
> @@ -264,7 +264,7 @@ print_man_node(MAN_ARGS)
>  		    n->flags & NODE_LINE && *n->string == ' ' &&
>  		    (h->flags & HTML_NONEWLINE) == 0)
>  			print_otag(h, TAG_BR, "");
> -		if (*n->string != '\0')
> +		if (want_fillmode == MAN_nf || *n->string != '\0')
>  			break;
>  		print_paragraph(h);
>  		return;
> @@ -338,8 +338,11 @@ print_man_node(MAN_ARGS)
>  	print_stagq(h, t);
>  
>  	if (fillmode(h, 0) == MAN_nf &&
> -	    n->next != NULL && n->next->flags & NODE_LINE)
> +	    n->next != NULL && n->next->flags & NODE_LINE) {
> +		/* In .nf = 
, print even empty lines. */
> +		h->col++;
>  		print_endline(h);
> +	}
>  }
>  
>  /*

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv