Bug 264501

Summary:	bc(1): Multiple issues in manual page
Product:	Documentation	Reporter:	CrazyMihey <CrazyMihey>
Component:	Manual Pages	Assignee:	Stefan Eßer <se>
Status:	In Progress ---
Severity:	Affects Some People	CC:	CrazyMihey, doc, gavin, pauamma, se, wosch
Priority:	---	Keywords:	needs-patch, needs-qa
Version:	Latest
Hardware:	Any
OS:	Any
URL:	HTTPS://WWW.FreeBSD.Org/cgi/man.cgi?query=bc

Description CrazyMihey 2022-06-06 16:03:28 UTC

Some Bad-Syllabification were Found in Man Pages of «General Commands»/«FreeBSD 13.1-Release and Ports»/«BC» (Command-Line Calculator).
HTTPS://WWW.FreeBSD.Org/cgi/man.cgi?query=bc
Beacose of Page-Width Limitations «-» is used
 1. Ambiguity in «SYNOPSIS» Section: It is not obvious about Correct Name of the Key: «--math-lib» or  «--mathlib».
 2. Broken Link in «DESCRIPTION» Section:
   2.1. «https://pubs.open-» must be «HTTPS://Pubs.OpenGroup.Org/onlinepubs/9699919799/utilities/bc.html»?
 3. Broken Link in «SYNTAX» Section:
   3.1. «https://pubs.opengroup.org/on-» must be «HTTPS://Pubs.OpenGroup.Org/onlinepubs/9699919799/utilities/bc.html»?
 4. The same as above ↑ in «SYNTAX/Operators» Section.
 5. The same as above ↑ in «LIBRARY/Standard Library» Section.
 6. The same as above ↑ in «LIBRARY/Extended Library» Section.
 7. Broken Link in «LIBRARY/Extended Library» Section in Functions «r», «ceil»:
   7.1. Function «r(x, p)»:
	«https://en.wikipedia.org/wiki/Round-» must be «HTTPS://En.WikiPedia.Org/wiki/Rounding#Rounding_away_from_zero»?
   7.2. Function «ceil(x, p)»
	«https://en.wikipedia.org/wiki/Round-» must be «HTTPS://En.WikiPedia.Org/wiki/Rounding#Rounding_away_from_zero»?
 8. Broken Link in «LIBRARY/Transcendental Functions» Section:
   8.1. «https://people.eecs.berke-/» must be «HTTPS://People.EECS.Berkeley.Edu/~wkahan/LOG10HAF.TXT»?
 9. The same as above ↑↑ in «INTERACTIVE MODE» Section.
10. The same as above ↑↑ in «TTY MODE» Section.
11. Broken Link in «BUGS» Section:
  11.1. «https://git.yzena.com/gavin/bc.» must be «HTTPS://Git.Yzena.Com/gavin/bc»?	# No Last PoInt «.» in HyperLink, It must stay just in Page Text, out of «<A HRef="…">» String.
All this ReMarks are not Critical, but can Help to Improve Quality of FreeBSD Documentation.
				Thank You for Attention, Best Regards, CrazyMihey.
P.S. I tried to Mail This to <FreeBSD-Doc<It is a Dog?>FreeBSD.Org>, but «the Mlmmj program» rejected My Letter, so I decided to Post It Here.

Comment 1 Stefan Eßer freebsd_committer

2022-06-07 19:07:17 UTC

(In reply to CrazyMihey from comment #0)

The documentation is generated from MarkDown sources and the issues seem to be the result of a less-than-optimal transformation process.

I'll forward the PR to Gavin Howard (gavin at yzena.com), the author of the program and its documentation to assess the cause of the problem.

Comment 2 Stefan Eßer freebsd_committer

2022-06-07 19:16:27 UTC

(In reply to Stefan Eßer from comment #1)

After checking the output of "man bc" and comparing the rendered text with the ASCII rendering on the web site https://www.freebsd.org/cgi/man.cgi?query=bc&format=ascii it appears to be an issue of this rendering process.

The man page is rendered correctly by mandoc - I'd have to check what programs are used for the web rendering.

Comment 3 Gavin D. Howard 2022-06-07 21:29:50 UTC

There are probably a couple things I can do to the Markdown to make it better as a webpage, but if it's an issue with FreeBSD's renderer, that would probably be a better place to fix it. Regardless, I'm willing.

Comment 4 Stefan Eßer freebsd_committer

2022-06-08 16:28:22 UTC

(In reply to Gavin D. Howard from comment #3)

I have found the cause of the broken elements and URLs:

The man page is rendered with "groff -man", and with default settings this enables block justification and hyphenation.

Adding 2 macros (.nh and .ad l) to the start of the man page solves the issue.

This causes left justified ragged lines and disables hyphenation.

But since the default settings are inappropriate (at least for man pages that contain long options in the SYNOPSYS and long URLs in the text), I'm wondering whether it might be possible to run "groff" with options that change the processing to no hyphenation and ragged lines without the need of macros in each affected man-page.

And I still do not understand why the man pages are formatted with groff, anyway. 

We have mandoc and it seems its default formatting option are sane ...

Comment 5 Pau Amma 2022-06-12 09:15:35 UTC

(In reply to Stefan Eßer from comment #4)

https://wiki.freebsd.org/Doc/IdeaList#Website carlavilla's working on it.