Re: [GTALUG] war story: fixing a doc bug can be hard

[o1bigtenor via talk]

On Wed, Apr 10, 2019 at 9:28 AM Lennart Sorensen via talk
 wrote:
>
> On Tue, Apr 09, 2019 at 04:27:14PM -0400, Stewart C. Russell via talk wrote:
> > Or get two 16x9s, and flip one vertically. It means your desktop looks a
> > bit O_o, but it works.
>
> I have seen dual 16x10 both turned vertically side by side which was
> a great desktop.  Displayport daisy chaining and a very thin bessel on
> the top made them very nice to setup.
>
Sorry - - - - I went to 4 - 1920 x 1080s.
1 in portrait mode on the left primarily for pdf and text work
3 in landscape mode with 2 stacked in the middle and one on the right.
2 virtual screens stitched together using Xinerama to give a 3940 x
3000 (h x v) setup and yes there is a hole in the display area that
cannot be displayed.
I've been toying with adding a 4k monitor to move this to a larger
area as even with the screen real estate I too often am hampered in
function.

Would suggest at least 2 monitors for any desktop unless you're going
for a 4k and even then I would suggest moving to 2 as well.
You will be surprised how much more you can get done in a period of time!

Regards
---
Talk Mailing List
talk@gtalug.org
https://gtalug.org/mailman/listinfo/talk

Re: [GTALUG] war story: fixing a doc bug can be hard

[Lennart Sorensen via talk]

On Tue, Apr 09, 2019 at 04:27:14PM -0400, Stewart C. Russell via talk wrote:
> Or get two 16x9s, and flip one vertically. It means your desktop looks a
> bit O_o, but it works.

I have seen dual 16x10 both turned vertically side by side which was
a great desktop.  Displayport daisy chaining and a very thin bessel on
the top made them very nice to setup.

-- 
Len Sorensen
---
Talk Mailing List
talk@gtalug.org
https://gtalug.org/mailman/listinfo/talk

Re: [GTALUG] war story: fixing a doc bug can be hard

[Stewart C. Russell via talk]

On 2019-04-09 1:47 a.m., D. Hugh Redelmeier via talk wrote:
> 
> I assume that there is some perl convention for documentation (POD?),
> but I'm not immersed in that culture.

Yeah, POD can make a decent man page without fiddling with groff. But
maybe test the source with sane-width terminals (<= 80 cols) to see if
any reformatting must be made.

Outside groff, there's also the Heirloom Documentation Tools
 which are somehow based
on the original Solaris source. A newer - and frankly glorious - option
is A G Rudi's Neatroff  that's not
only able to typeset bi-di texts but it also handles Opentype ligatures
for efficient handling of Arabic and Farsi.

> |How many people are limited to 80 columns.
> 
> You are being sarcastic, right?

80 column terminals aren't the thing amongst the kids today. Used to
work with folks who'd use full-screen terminals with 8 px fonts, and not
windowed with tmux or anything.

> Buy an UltraHD TV or monitor. 

Or get two 16x9s, and flip one vertically. It means your desktop looks a
bit O_o, but it works.

cheers,
 Stewart

---
Talk Mailing List
talk@gtalug.org
https://gtalug.org/mailman/listinfo/talk

Re: [GTALUG] war story: fixing a doc bug can be hard

[D. Hugh Redelmeier via talk]

| From: Howard Gibson via talk 

|I am working on a Perl app, and I have written a man page for it.  I 
|do not expect to learn groff ever.  I can hack something that seems 
|to work.

You just have to take a sample man page and hack it into your man
page.  Until you need to do something tricky.

I assume that there is some perl convention for documentation (POD?),
but I'm not emersed in that culture.

|How many people are limited to 80 columns.

You are being sarcastic, right?

|Please note that I have problems with wide web pages.  I have my 
|1080p internet screen divided between my browser, my email and my 
|FVWM buttons.  A lot of web pages do not fit in the space I leave 
|them.  I hate them.

HTML has been a battleground between purists who think rendering is
the business of the, uhh, renderer (i.e. on the client side) and the
"designers" who are sure that they need control.  Both have a point
but the wrong side has been winning for 20 years.

Heaven help you if you are vision-impaired or you are trying to view
on an uncommon device or with a minority browser.

Buy an UltraHD TV or monitor.  Or put your buttons on the bottom (I
hate that because the normal aspect ratios are too wide so putting
buttons on the bottom makes that even worse).
---
Talk Mailing List
talk@gtalug.org
https://gtalug.org/mailman/listinfo/talk

Re: [GTALUG] war story: fixing a doc bug can be hard

[Howard Gibson via talk]

On Mon, 8 Apr 2019 10:48:59 -0400 (EDT)
"D. Hugh Redelmeier via talk"  wrote:

> I'm reading dnf(8) on Fedora 29 and get irked by the layout of the
> options.
> --disableexcludes=[all|main|],
> --disableexcludepkgs=[all|main|]
> 
> Here's what "man dnf" shows on a terminal that is 80
> columns wide.  Ugly.
> 
>--disableexcludes=[all|main|],   --disableexcludep‐
>kgs=[all|main|]

Hugh,

   I am working on a Perl app, and I have written a man page for it.  I do not 
expect to learn groff ever.  I can hack something that seems to work.  How many 
people are limited to 80 columns.

   Please note that I have problems with wide web pages.   I have my 1080p 
internet screen divided between my browser, my email and my FVWM buttons.  A 
lot of web pages do not fit in the space I leave them.  I hate them.  

-- 
Howard Gibson 
hgib...@eol.ca
jhowardgib...@gmail.com
http://home.eol.ca/~hgibson
---
Talk Mailing List
talk@gtalug.org
https://gtalug.org/mailman/listinfo/talk

[GTALUG] war story: fixing a doc bug can be hard

[D. Hugh Redelmeier via talk]

I'm reading dnf(8) on Fedora 29 and get irked by the layout of the
options.
--disableexcludes=[all|main|],
--disableexcludepkgs=[all|main|]

Here's what "man dnf" shows on a terminal that is 80
columns wide.  Ugly.

   --disableexcludes=[all|main|],   --disableexcludep‐
   kgs=[all|main|]

For those of you with MUAs that mangle this kind of stuff: the two
options don't fit on one line so something broke the line in a
terrible place and then filled the whitespace to justify the result.

It would be a lot better to just break the line at the whitespace and
to not justify the result.  The "not justify" part should just fall
out of there being no whitespace to stretch.

In an attempt to fix this, I tried to figure out how this problem
arose.  Surely this would be easy -- I was a troff adept forty years
ago.  And surely troff couldn't have change much because
(1) the orginal author, Joe Osssanna, died in 1977
(2) (I think) it is chained down by POSIX standard
(3) the language rules made it hard to extend

It turns out that the document representation and transformation isn't
what I thought it was.  It used to be that one wrote man pages in
troff, using the "an" macros, optionally with tbl preprocessing for
tables.

The dnf documentation is in a Python representation called
reStructured Text (.rst), not troff.

The .rst gets formatted by a thing called sphinx, a complex Python
system.  Among other things, it produces a formatted manpage that gets
shipped inside the dnf RPM.  So that seems easy, if odd.

But no.  That formatting cannot take account of terminal width or
characteristics.  So the man command, when confronted with one of
these files, process it in an intricate way, approximately:

gunzip -c /usr/share/man/man8/dnf.8.gz |
/usr/bin/preconv -e UTF-8 |
/usr/bin/tbl |
/usr/bin/nroff -mandoc -Tutf8 |
/usr/bin/less -r

The most peculiar part of that pipeline preconv.  It converts the
formatted document back into troff input!

In the case of dnf(8), the resulting troff file has a few problems
with the paragraph for these option but they don't explain this
particular misformatting.

The main problem seems to be in the "andoc" macros or in groff (the
GNU implementation of *roff).  And yes, groff has differences from the
troff I knew 40 years ago.

Getting this far in the problem has taken a few steps.

- download the source for dnf and build the .rpm

- attempt to figure out what builds what.  The build log isn't as
  clear as I'd hope.  I mistakenly thought it was rst2man but it is
  sphinx (they do share code).

- air my issues on an appropriate mailing list.  Contrary to the
  documentation, you actually have to join the list to post.
  So far this is the only traffic on the list this month.
  

Current state:

- I think that some things are wrong with the resulting ephemeral nroff 
  document but I don't know what's at fault and it isn't too important to 
  me.  I've reported it to the responsible authorities but I'm not sure 
  that they accept that there are problems.

- nroff -mandoc is doing something inappropriate with .TP macros but I
  don't know where the blame lies.  It surely requires engaging with
  another community.  I may run out of steam before getting farther.
  ---
Talk Mailing List
talk@gtalug.org
https://gtalug.org/mailman/listinfo/talk