[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

--- Comment #7 from Graham Perrin  ---
> ⋯ I might share something to make texts upright ⋯

Maybe not. If I understand correctly, things such as 

font-style: normal;

– can not be effective against italics, as seen even when I use (for
example) the View menu of Firefox to prefer no style for the page style :-(

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

--- Comment #6 from G. Branden Robinson  ---
(In reply to Wolfram Schneider from comment #3)

Hi Wolfram!

(I will try harder to get your name correct--people misspell mine all the time,
so I really shouldn't mess up others' names.)

"This is very likely a side effect of the groff 1.23.0 update.

I don't know why, I will check.

...

I think problem is in the new variable doc-page-topic-font

/usr/local/share/groff/1.23.0/tmac/mdoc/doc-nroff
.ds doc-page-topic-font \f[I]

if you change that to

.ds doc-page-topic-font \f[]

the title will be displayed without italic fonts

...

commit eeb7e34a074014631c5feab8121928a9b2ddc7a2
Author: G. Branden Robinson 
Date:   Thu Nov 3 07:16:41 2022 -0500"

That is indeed the commit that changes the page topic to use the same face as
the _mdoc_ `Xr` macro, which (as of _groff_ 1.23.0) also uses italics by
defaults.

However, as you've found, this setting is also customizable, and there's
nothing wrong with changing it.

I would not, however, make the exact change you proposed.

.ds doc-page-topic-font \f[]

This doesn't make a "null font change": it changes the font to the _previously
selected_ font.  Sometimes this will have no adverse consequences, but I
wouldn't bet on it never doing so, and it's the sort of thing that can be hard
to track down later.

If you want the page topic to render in roman, I would say so explicitly.

.ds doc-page-topic-font \f[R]

In _groff_ 1.24.0 I hope to get the `MF` string from _groff man_ ported over to
our _mdoc_ implementation to improve the package-neutral configurability of man
page appearance.  (The reasons this wasn't already done have to do with PDF
support for hyperlinks, whether internal or of the "man:ls(1)" kind; it's
easier for me to develop features for _man_(7), get the bugs shaken out, then
port them over to _mdoc_.)

If you want to eliminate the appearance of italic text in _mdoc_ documents as a
low-vision accommodation measure (or for any other reason), you might also want
to look at some other string definitions.  In _groff_ 1.22.4 (and "nroff
mode"), the `Ad`, `Ar`, `Em`, `Fa`, `Ft`, `Pa`, `Sx`, and `Va` also used
italics, as did the fixed string `Na` (which writes "NaN").  This list is
mostly the same in _groff_ 1.23.0, with the removal of `Sx` and addition of
`Xr`.

Regarding text appearing in green, that is not anything _groff_ does by
default; _groff_ itself does not colorize man pages.  (It's overwhelmingly
popular among Arch Linux users.)  Based on experience with other man-to-HTML
converters, I surmise that what's happening is that a tool is telling _groff_
to format a man page for a terminal and then interpreting the output to infer
typeface changes.  A CSS style may then be getting applied to the inferred
faces.

Regarding the accessibility issues of italic text, I think it's important to
keep the domain of application in mind.  As pointed out in the top link
matching your "startpage" query,

https://ux.stackexchange.com/questions/62742/are-italics-on-the-web-bad-for-accessibility

...it seems that some people are interpreting a blanket prohibition against
italics for Web content by (arguably) overreading a W3C recommendation. 
Whether the problems that degrade the readability of italics apply to the
FreeBSD web site is something that the FreeBSD project should decide for
itself.

I will add that in _groff_ 1.23.0 italics are not used by default when
rendering to terminals.  It can be enabled, however.  _grotty_, _groff_'s
output driver for terminals, has long supported the production of ISO
6429/ECMA-48 SGR escape sequences for italics, but the switch to enable these
has not been easy to access.  It is now.

https://git.savannah.gnu.org/cgit/groff.git/tree/NEWS?h=1.23.0#n86

Still, as I said, italics in terminal output are _off_ by default.  This might
change in _groff_ 1.24.0, as Lennart Jablonka has proposed patches to make
_grotty_ use _terminfo_ to determine the terminal's capabilities instead of
firing blindly as it has done to date.

https://lists.gnu.org/archive/html/groff/2023-09/msg00027.html

Traditionally, "nroff devices" use underscores in place of italics, because the
typewriter-based paper terminals that _roff_ and _nroff_ targeted in the early
1970s did not support oblique typefaces.  Apparently (per the above Stack
Exchange thread), at one point the British Dyslexia Association discouraged
thae underscoring practice as well...but the link is now dead.  Whether this
suggests that the corresponding guidance has been withdrawn, I cannot say.

Finally, I would emphasize that _groff_, like the _troff_ from Bell Labs that
inspired it, is a typesetting system.  At the aforementioned StackExchange
thread, much of the quoted discussion expressing concern with the accessibility
of italic text to those with low vision centered on issues of poor font quality
or low-resolution glyph rendering.  _groff_ is indeed designed to format text
even in such

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

Graham Perrin  changed:

   What|Removed |Added

   See Also||https://bugs.freebsd.org/bu
   ||gzilla/show_bug.cgi?id=2739
   ||03

--- Comment #5 from Graham Perrin  ---
Thanks

(In reply to Graham Perrin from comment #0)

> Generally

>> ⋯ italic text is often difficult to read with low vision, ⋯

For the  view of things, would a style sheet (theme)
menu be out of scope for the FreeBSD Project? 

I could raise the accessibility issue through the Bugs menu at
, however the need for upright text
will probably be at odds with e.g . 



If out of scope, then – as I did for comment widths in Bugzilla
 – I might share something to make texts
upright at man.freebsd.org ⋯

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273903] groff 1.23.0 metabug

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273903

Graham Perrin  changed:

   What|Removed |Added

   See Also||https://bugs.freebsd.org/bu
   ||gzilla/show_bug.cgi?id=2738
   ||85

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273903] groff 1.23.0 metabug

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273903

Graham Perrin  changed:

   What|Removed |Added

   Keywords||tracking

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 251866] Because the loader.efi modified the size of EFI_STAGING_SIZE, vmware could not start the system above FreeBSD 12.2

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=251866

Graham Perrin  changed:

   What|Removed |Added

 Attachment #224114|0   |1
is obsolete||

--- Comment #39 from Graham Perrin  ---
Comment on attachment 224114
  --> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=224114
13.0-RELEASE not booting – UEFI – HP ProBook 440 G7

Obsolete (irrelevant) in the context of comment 30 (2021-04-14). 

What's observed in photographs such as this was fixed in FreeBSD 13.1-RELEASE
(2022-05-16). From
: 

> UEFI boot is improved for amd64. ⋯ (Sponsored by The FreeBSD Foundation)

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 251866] Because the loader.efi modified the size of EFI_STAGING_SIZE, vmware could not start the system above FreeBSD 12.2

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=251866

Graham Perrin  changed:

   What|Removed |Added

   Priority|Normal  |---
   See Also||https://bugs.freebsd.org/bu
   ||gzilla/show_bug.cgi?id=2478
   ||45
  Flags|mfc-stable12?   |
 CC|grahamper...@freebsd.org|d...@freebsd.org
   Keywords||loader, needs-patch, uefi
URL||https://github.com/freebsd/
   ||freebsd-doc/blob/main/websi
   ||te/content/en/releases/12.2
   ||R/errata.adoc#open-issues

--- Comment #38 from Graham Perrin  ---
 will benefit from
a belated link to this bug 251866, or, at least, an outline of the loader.efi
issue. Keyword: 

* needs patch


(In reply to Warner Losh from comment #36)

I hesitate before closing this report only because of the regression keyword.

Given: 

a) 13.0-RELEASE  announced 
   more than two years ago

b) 12.4-RELEASE no longer recommended for new deployments

c) stable/12 reaching end of life in less than three months

d) the available resolution for users of supported versions of FreeBSD 12.⋯
   (upgrade to VMware vSphere ESXi 8.0 or greater)

– I do think that documentation and then closure will be reasonable.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273901] Handbook: Automatically Switching to Headphones: More explanation needed

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273901

Graham Perrin  changed:

   What|Removed |Added

URL||https://github.com/freebsd/
   ||freebsd-doc/blob/main/docum
   ||entation/content/en/books/h
   ||andbook/multimedia/_index.a
   ||doc#24-automatically-switch
   ||ing-to-headphones
   Keywords||needs-patch, needs-qa
 Status|New |Open
   See Also||https://bugs.freebsd.org/bu
   ||gzilla/show_bug.cgi?id=2738
   ||09

--- Comment #1 from Graham Perrin  ---


-- 
You are receiving this mail because:
You are the assignee for the bug.

Problem reports for d...@freebsd.org that need special attention

[bugzilla-noreply]

To view an individual PR, use:
  https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=(Bug Id).

The following is a listing of current problems submitted by FreeBSD users,
which need special attention. These represent problem reports covering
all versions including experimental development code and obsolete releases.

Status  |Bug Id | Description
+---+---
Open|272260 | bectl(8) usage: -?

1 problems total for which you should take action.

[Bug 212155] Incorrect documentation in cam(4) for wired scsi device hints.

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=212155

--- Comment #6 from commit-h...@freebsd.org ---
A commit in branch main references this bug:

URL:
https://cgit.FreeBSD.org/src/commit/?id=c2909b0c9a29cd6fa0019ed9998dde9e054bdad2

commit c2909b0c9a29cd6fa0019ed9998dde9e054bdad2
Author: Tom Hukins 
AuthorDate: 2023-09-17 15:12:22 +
Commit: Warner Losh 
CommitDate: 2023-09-17 15:13:49 +

cam(4): Fix device hints documentation

The code in sys/cam/cam_periph.c that calls resource_int_value(9) looks
for "lun" not "unit".

PR: 212155
Reviewed by: imp
Pull Request: https://github.com/freebsd/freebsd-src/pull/843

 share/man/man4/scsi.4 | 8 
 1 file changed, 4 insertions(+), 4 deletions(-)

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273903] groff 1.23.0 metabug

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273903

Wolfram Schneider  changed:

   What|Removed |Added

 Depends on||273255


Referenced Bugs:

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273255
[Bug 273255] textproc/groff: regression in 1.23.0 if using custom fonts
-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273245] textproc/groff: groff_mdoc(7): output from 'man 7 groff_mdoc' is badly broken

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273245

Wolfram Schneider  changed:

   What|Removed |Added

 Status|Open|In Progress

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273690] mdoc .Fx macro: Unknown FreeBSD version

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273690

Wolfram Schneider  changed:

   What|Removed |Added

 Status|Open|In Progress

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273443] Broken FreeBSD man pages portal

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273443

Wolfram Schneider  changed:

   What|Removed |Added

 Depends on||273903


Referenced Bugs:

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273903
[Bug 273903] groff 1.23.0 metabug
-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273903] groff 1.23.0 metabug

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273903

Wolfram Schneider  changed:

   What|Removed |Added

 Status|New |Open
 Blocks||273245, 273443, 273599,
   ||273565


Referenced Bugs:

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273245
[Bug 273245] textproc/groff: groff_mdoc(7): output from 'man 7 groff_mdoc' is
badly broken
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273443
[Bug 273443] Broken FreeBSD man pages portal
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273565
[Bug 273565] latest groff 1.23.0 is incompatible with FreeBSD
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273599
[Bug 273599] outdated textproc/groff/files/mdoc.local
-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273245] textproc/groff: groff_mdoc(7): output from 'man 7 groff_mdoc' is badly broken

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273245

Wolfram Schneider  changed:

   What|Removed |Added

 Depends on||273903


Referenced Bugs:

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273903
[Bug 273903] groff 1.23.0 metabug
-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273903] groff 1.23.0 metabug

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273903

Bug ID: 273903
   Summary: groff 1.23.0 metabug
   Product: Documentation
   Version: Latest
  Hardware: Any
OS: Any
Status: New
  Severity: Affects Some People
  Priority: ---
 Component: Manual Pages
  Assignee: b...@freebsd.org
  Reporter: wo...@freebsd.org
CC: d...@freebsd.org

A place to record all issues with the upgrade to groff 1.23.0

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

Wolfram Schneider  changed:

   What|Removed |Added

 CC||g.branden.robin...@gmail.co
   ||m

--- Comment #4 from Wolfram Schneider  ---
commit eeb7e34a074014631c5feab8121928a9b2ddc7a2
Author: G. Branden Robinson 
Date:   Thu Nov 3 07:16:41 2022 -0500

[mdoc]: Set man page topic names in italics.

* tmac/mdoc/doc-ditroff (doc-page-topic-font):
* tmac/mdoc/doc-nroff (doc-page-topic-font): Set man page topic names in
  italics.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

Wolfram Schneider  changed:

   What|Removed |Added

 Status|Open|In Progress

--- Comment #3 from Wolfram Schneider  ---
I think problem is in the new variable doc-page-topic-font

/usr/local/share/groff/1.23.0/tmac/mdoc/doc-nroff
.ds doc-page-topic-font \f[I]

if you change that to

.ds doc-page-topic-font \f[]

the title will be displayed without italic fonts

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

Wolfram Schneider  changed:

   What|Removed |Added

   Assignee|b...@freebsd.org|wo...@freebsd.org
 CC||wo...@freebsd.org

--- Comment #2 from Wolfram Schneider  ---
This is very likely a side effect of the groff 1.23.0 update.

I don't know why, I will check.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273901] Handbook: Automatically Switching to Headphones: More explanation needed

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273901

Bug ID: 273901
   Summary: Handbook: Automatically Switching to Headphones: More
explanation needed
   Product: Documentation
   Version: Latest
  Hardware: Any
OS: Any
Status: New
  Severity: Affects Some People
  Priority: ---
 Component: Books & Articles
  Assignee: d...@freebsd.org
  Reporter: j...@freebsd.org

I'm trying to get a better understanding of how to diagnose sound issues on
FreeBSD.

The handbook, under "Automatically Switching to Headphones", contains the
following example:

===
Some systems may struggle with switching between audio outputs, but fortunately
FreeBSD allows automatic switchover to be configured in device.hints.

Identify how the system is enumerating the audio outputs by executing the
following command:

% dmesg | grep pcm

The output looks something like this:

pcm0:  at nid 23 and 26 on hdaa0
pcm1:  at nid 22 on hdaa0

Add the following lines to /boot/device.hints:

hint.hdac.0.cad0.nid22.config="as=1 seq=15 device=Headphones"
hint.hdac.0.cad0.nid26.config="as=2 seq=0 device=speakers"
===

It is not at all evident how the values of "as" and "seq" were determined from
the dmesg output above. 

Also, running "dmesg | grep pcm" does not even reveal which device is the
headphone jack on my Lenovo T430.  I suspect the details provided to dmesg are
highly variable across devices.

===
FreeBSD moray.acadix  bacon ~ 1004: dmesg|grep pcm
pcm0:  at nid 20 and 24 on hdaa0
pcm1:  at nid 21 and 18 on hdaa0
pcm2:  at nid 5 on hdaa1
pcm3:  at nid 6 on hdaa1
pcm4:  at nid 7 on hdaa1
pcm0:  at nid 20,21 and 24 on hdaa0
pcm1:  at nid 18 on hdaa0
pcm2:  at nid 5 on hdaa1
pcm3:  at nid 6 on hdaa1
pcm4:  at nid 7 on hdaa1
===

Maybe the handbook should explain how to use "sysctl dev.hdac.0.pindump=1" and
"dmesg" to obtain that information?  Another developer pointed me to this
method in bug #273809.

===
<<>> /home/bacon 1063 # sysctl dev.hdac.0.pindump=1
dev.hdac.0.pindump: 0 -> 0
<<>> /home/bacon 1064 # dmesg | awk '$2 == "nid" || $6 ==
"Headphones"'
hdaa0: nid   0xas seq device   conn  jackloccolor   misc
hdaa0: 21 0321101f 1  15 HeadphonesJack  1/8 Left   Black   0
hdaa0: 27 6121113f 3  15 HeadphonesNone  1/8 Ext-Rear   Black   1 DISA
hdaa1: nid   0xas seq device   conn  jackloccolor   misc
===

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug 273895] Git for status reports: discourage inappropriate squashes and force-pushes

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273895

Graham Perrin  changed:

   What|Removed |Added

 Status|New |Open

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug 273895] Git for status reports: discourage inappropriate squashes and force-pushes

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273895

Bug ID: 273895
   Summary: Git for status reports: discourage inappropriate
squashes and force-pushes
   Product: Documentation
   Version: Latest
  Hardware: Any
   URL: https://github.com/freebsd/freebsd-doc/blob/main/docum
entation/content/en/articles/freebsd-status-report-pro
cess/_index.adoc
OS: Any
Status: New
  Keywords: needs-patch
  Severity: Affects Some People
  Priority: ---
 Component: Website
  Assignee: d...@freebsd.org
  Reporter: grahamper...@gmail.com
CC: salvad...@freebsd.org

From

(archived): 

> … please, do not squash or force-push (doing so will make the next 
> review much more difficult). …

 lacks
this discouragement. 

I can prepare a patch, for attachment to this bug report. 

Thanks to @salvadore for helping me to rediscover the archived point of
reference.

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

--- Comment #1 from Graham Perrin  ---
> … 
> 
>  
> particularly difficult, …

Sorry, I forgot to trim that URL. 

Instead: 



Captured: 



-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

Graham Perrin  changed:

   What|Removed |Added

 Status|New |Open

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 261349] Modernise hier(7)

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261349

Graham Perrin  changed:

   What|Removed |Added

   See Also||https://bugs.freebsd.org/bu
   ||gzilla/show_bug.cgi?id=2738
   ||85

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug 273885] Accessibility: review use of italicised green monospace in manual pages

[bugzilla-noreply]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273885

Bug ID: 273885
   Summary: Accessibility: review use of italicised green
monospace in manual pages
   Product: Documentation
   Version: Latest
  Hardware: Any
OS: Any
Status: New
  Keywords: accessibility
  Severity: Affects Many People
  Priority: ---
 Component: Manual Pages
  Assignee: b...@freebsd.org
  Reporter: grahamper...@gmail.com
CC: d...@freebsd.org

Today, at first sight,

appeared wrong. 

First line (header of the manual content): the italicised green monospace
words, immediately adjacent to upright non-green numbers in parentheses. 

Comparing with a recent capture from
, I assume that
the change from upright black to italicised green, in headers and footers, is
fairly recent. 

8th August 2023:

– upright black.

manpath=freebsd-current for the same page, captured today:

– italicised green.

Generally
=

Amongst the top five results for
:
 

Font - Low Vision Accessibility Task Force


Quote: 

> italic text is often difficult to read with low vision, 

I find

particularly difficult, and so on.

-- 
You are receiving this mail because:
You are on the CC list for the bug.