JC, thanks for the information. certainly food for thought. its too bad there is no way to convert back from html. that would make life a lot easier for some of us who can code there (not me). still, having options for conversion from the new man format to css, html, pdf and others is very nice indeed. the nice thing about a properly formatted pdf is that I can use a number of very accessible programs to read it.
give me a year and I should also know braille sufficiently to make reading man pages a bit easier (although I would still prefer a more usable format for editing, etc. I hope no one minds that I shamelessly plug the OpenBSD site in the subject line. this should allow word in the search engines to better reflect a useful project such as this. -eric On Jul 28, 2012, at 1:32 AM, J.C. Roberts wrote: > Hi Eric, > I noticed your comments and questions on misc@openbsd regarding access > for the blind when reading and editing man pages through a screen > reader. For just reading man pages at a terminal, converting into pure > text will most likely help you, and it could be very useful when > working on remote systems via ssh. The command to get the plain text of > a man page is: > > $ man man_page_name | col -bx | less > > Where the "man_page_name" is replaced by the name of the manual you > want. The trick is to use the col command to strip out the unwanted > stuff like the character sequences indicating bold, italics, color and > similar. This will work on most UNIX systems. > > I'm not sure if the pipe to less is needed, since you might be > able to pipe the output directly into your screen reader when working > locally or running X forwarding with audio on the remote system. Also, > I should mention that the default behavior of the man command in the > above is equivalent to using the -c flag with the man command such > as "man -c man_page_name" since the output is to a pipe rather than a > terminal. This simply by passes the default pager more or less. > > That was the worst pun I've ever written. :) > > To be clear, when the man command outputting to a pipe rather than a > terminal, the default pager is by passed regardless if you're using the > more command or the less command as your default pager. This may not be > the case on all UNIX systems, so you might need to use the -c flag or > equivalent on some systems. > > When you're on OpenBSD or any system with mandoc available, another > way to output as plain text is: > > $ mandoc -Tascii man_page_name | col -bx | less > > When converting to plain text, you lose the visual hints such as bold, > italics, colors, and indentation based grouping. Depending on the > screen reader you use and how you have it configured, this may or may > not make a difference to you. If you'd prefer how html is read, then > converting to html is easy with mandoc. It can convert man pages to CSS1 > and HTML-4.01 compliant output, or alternatively, to CSS1 and XHTML-1.0 > output, depending on the argument used with the -T flag. > > If indentation is helpful to you in some way, be sure to check out the > "tree" argument of the -T flag in mandoc. > > I don't have much personal experience using modern screen readers or > magnifiers, but I've set them up in the past on microsoft windows for > family friends. Within limitations, I can see fairly well and my > personal vision problems are somewhat convoluted. I'm overly sensitive > to light, so it's only a disadvantage most of the time, but at other > times, like at night, it can actually be an advantage. > > The new mdoc format is a markup language. the same is true for the > original man format, see "man 7 man". Unlike html, both the mdoc and > old man formats are designed to be parsed and converted in many > different ways by many different programs. You know this already since > you know it's possible to convert man pages into html and read them in > a web browser. The problem with doing converting to html is you're > unable to convert back into the required raw man or mdoc format. > > For example the mandoc command can output manual pages converted to > html, but it does not accept html as an input type, so any changes done > to the html are useless. > > Most people learn the markup syntax and work with the raw man or mdoc > markup format files in a text editor. I can imagine how the raw markup > format would be tough to read, or better said, hear, through a normally > configured screen reader. I know some screen readers are used for > coding, but I've never witnessed one in use by a programmer. It may or > may not be possible to teach the screen reader about the idiosyncrasies > and rules of the markup language to make hearing the raw format a bit > more bearable and useful. > > Whether seen or spoken, all markup languages are ugly, and the raw > markup formats used for manuals are some of the absolute worst. This is > especially true for the old style man pages based on roff, troff, groff > and friends. The new mdoc format is a significant improvement. On the > bright side, the manual markup formats are also some of the best and > most flexible when it comes to generating output in various formats. > > I hope this helps. > > Kind regards > j.c.r.
