bugGNU roff - Bugs: bug #64501, grohtml(1): confusing sentence in...

 
 

bug #64501: grohtml(1): confusing sentence in "Bugs" section

Submitter:  Dave <barx>
Submitted:  Tue 01 Aug 2023 07:48:41 AM UTC
   
 
Category:  Driver grohtml Severity:  2 - Minor
Item Group:  Documentation Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 15 Aug 2023 02:43:39 AM UTC, comment #8: 

comment #7:

> I think resolving this one amounts to understanding why the
> unintended hyphenation occurs.


First comes defining what "the unintended hyphenation" is.  The current Bugs wording (which I'll dub the Space Bug) and the text Gaius proposed in comment #1 (henceforth the Header Bug) may not be describing the same bug.  I'm less than certain about this because I'm still not sure I understand what the former is trying to say, though I took a stab at an interpretation in comment #4.  But there may be more than one hyphenation-based problem.

> I have a hypothesis in comment #3,


This hypothesis appears to relate to the Header Bug.  The Space Bug (as interpreted in comment #4) seems to hinge on the "Why doesn't that work?" query in comment #5.

Dave <barx>
Group Member
Fri 04 Aug 2023 06:46:32 PM UTC, comment #7: 


comment #6:

> comment #5:
> > comment #4:
> > > the user might want lines in the HTML source broken in
> > > reasonable places for easier handling in a text editor.
> >
> > But that's not the source form of the document, so why
> > would they bother?
>
> Who can understand the inscrutable actions of users?
>
> But point taken; a more realistic reason might be for easier viewing in "less".  Sometimes it's a little easier to work with lines of manageable length, and if the HTML renderer doesn't care, why not let groff generate the easier-for-humans thing?


I agree, but it's a value-add.  Not necessarily to be postponed until everything "more important" is done, but a task to be snatched when it promises to be easy to resolve.
 

> > >  To an HTML renderer, a space and a newline are equivalent,
> >
> > Except when <pre> is used.
>
> Also a good point.


I'd like to make it a moot one instead; bug #61915.
 

> > > I see no downside to this for the vertical dimension.
> >
> > I see none for the horizontal dimension either,
>
> It's admittedly a nicety, but one that can certainly be punted down the line until the software stops referring to itself as beta code.  There are much bigger grohtml fish to fry.  (And some of its most glaring limitations seem to not even have Savannah tickets.)


Yeah. :(

> But all this seems far afield of the original bug report and perhaps ought to have its own ticket.


I think resolving this one amounts to understanding why the unintended hyphenation occurs.  I have a hypothesis in comment #3, but it needs testing.  If it's easy to fix, then this ticket morph into a code defect rather than a documentation defect.  If it's hard, we'll at least be able to update the man page with enough understanding to guide the user to a workaround.

G. Branden Robinson <gbranden>
Group administrator
Fri 04 Aug 2023 06:28:15 PM UTC, comment #6: 

comment #5:

> comment #4:
> > the user might want lines in the HTML source broken in
> > reasonable places for easier handling in a text editor.
>
> But that's not the source form of the document, so why
> would they bother?


Who can understand the inscrutable actions of users?

But point taken; a more realistic reason might be for easier viewing in "less".  Sometimes it's a little easier to work with lines of manageable length, and if the HTML renderer doesn't care, why not let groff generate the easier-for-humans thing?

> >  To an HTML renderer, a space and a newline are equivalent,
>
> Except when <pre> is used.


Also a good point.

> > I see no downside to this for the vertical dimension.
>
> I see none for the horizontal dimension either,


It's admittedly a nicety, but one that can certainly be punted down the line until the software stops referring to itself as beta code.  There are much bigger grohtml fish to fry.  (And some of its most glaring limitations seem to not even have Savannah tickets.)

But all this seems far afield of the original bug report and perhaps ought to have its own ticket.

Dave <barx>
Group Member
Fri 04 Aug 2023 03:57:00 AM UTC, comment #5: 

comment #4:

> comment #2:
> > the user ought to be strongly encouraged to disable automatic
> > hyphenation in documents targeting HTML.
>
> Self follow-up: it turns out the user needn't be encouraged or discouraged from any such thing, as tmac/html.tmac already disables hyphenation and disallows the user to turn it back on: http://git.savannah.gnu.org/cgit/groff.git/tree/tmac/html.tmac?id=a246806d81351996ac2fa4a8f0826915e576bc0f#n25


Yeah, I'm uneasy about that.

> comment #3:
> > grohtml does try to set the line length really long.
>
> In light of the above, this seems unnecessary, and potentially even counterproductive: the user might want lines in the HTML source broken in reasonable places for easier handling in a text editor.


But that's not the source form of the document, so why would they bother?

If someone needs to finagle grohtml(1) output, sed(1) is available, as are text editors that are old hands at managing insanely long lines of text.

>  To an HTML renderer, a space and a newline are equivalent, so where line breaks occur in the HTML that groff outputs won't affect the rendered page at all.


Except when <pre> is used.  But that's a crude tool that I want to get us away from.  We should change the font family with CSS style attributes or an equivalent.
 

> ...with one exception, and that is if groff breaks a word at a hard hyphen, which it is usually free to do regardless of the hyphenation setting.  It strikes me now that this may be what the incomprehensible(-to-me) sentence that launched this bug was trying to get at.


> On the third hand, even that ought to be disabled by the .cflags line in html.tmac (see the link above).


Right.  Why doesn't that work?

> So I'm no more enlightened than when I started this reply.


We'll get you (along with the rest of us) there eventually.

> > We could define a new papersize that is effectively infinite
> > in both dimensions...
>
> I see no downside to this for the vertical dimension.


I see none for the horizontal dimension either, but perhaps I have about as callous an attitude toward the readability of grohtml(1) output as the authors of docbook-to-man had toward my beloved man(7) format.

G. Branden Robinson <gbranden>
Group administrator
Thu 03 Aug 2023 11:53:37 PM UTC, comment #4: 

comment #2:

> the user ought to be strongly encouraged to disable automatic
> hyphenation in documents targeting HTML.


Self follow-up: it turns out the user needn't be encouraged or discouraged from any such thing, as tmac/html.tmac already disables hyphenation and disallows the user to turn it back on: http://git.savannah.gnu.org/cgit/groff.git/tree/tmac/html.tmac?id=a246806d81351996ac2fa4a8f0826915e576bc0f#n25


comment #3:

> grohtml does try to set the line length really long.


In light of the above, this seems unnecessary, and potentially even counterproductive: the user might want lines in the HTML source broken in reasonable places for easier handling in a text editor.  To an HTML renderer, a space and a newline are equivalent, so where line breaks occur in the HTML that groff outputs won't affect the rendered page at all.

...with one exception, and that is if groff breaks a word at a hard hyphen, which it is usually free to do regardless of the hyphenation setting.  It strikes me now that this may be what the incomprehensible(-to-me) sentence that launched this bug was trying to get at.

On the third hand, even that ought to be disabled by the .cflags line in html.tmac (see the link above).  So I'm no more enlightened than when I started this reply.

> We could define a new papersize that is effectively infinite
> in both dimensions...


I see no downside to this for the vertical dimension.

Dave <barx>
Group Member
Thu 03 Aug 2023 10:36:18 PM UTC, comment #3: 

I once saw a problem caused by the following, but I can't remember if it was in grohtml or someplace else.

grohtml does try to set the line length really long.


tmac/html.tmac:.mso www.tmac
tmac/troffrc-end:.      do mso www.tmac

tmac/www.tmac.in:.      ll 1000n
tmac/www.tmac.in:.      ll 1000n


I see two problems here.  First, 1000n may not be enough.  But we can fix that, especially if we do what I intend with the `.R` register (bug #63587).

The second and worse problem is that this changed line length does not alter the line length used in environments.

Environments are initialized with formatting parameters corresponding to the formatter's defaults.  (The output device has defaults for a paper format, but the 'html' device doesn't use them, so you get the formatter's defaults.)

I suppose the "real fix" for this is to give groff's 'html' device some default paper dimensions that make sense when it's actually formatting.  We could define a new papersize that is effectively infinite in both dimensions...

G. Branden Robinson <gbranden>
Group administrator
Tue 01 Aug 2023 04:55:12 PM UTC, comment #2: 

comment #1:

> Maybe an improved statement would be:
>
> grohtml does not accurately support hyphenation and sometimes it
> is necessary to set the page width to a large value to avoid
> generating an hyphenation in the title (using ms macro set).


That's perfectly comprehensible, but "does not accurately support" is still vague about what grohtml does or does not do with word breaking.

In general--and in contrast to every other output device groff supports--the page layout for HTML will be done by software well outside groff's control, so the user ought to be strongly encouraged to disable automatic hyphenation in documents targeting HTML.

Dave <barx>
Group Member
Tue 01 Aug 2023 12:34:43 PM UTC, comment #1: 

Ah yes - this is extremely poorly worded (and wrong).  It looks garbled.  Maybe an improved statement would be:

grohtml does not accurately support hyphenation and sometimes it is necessary to set the page width to a large value to avoid generating an hyphenation in the title (using ms macro set).

Gaius Mulley <gaius>
Group Member
Tue 01 Aug 2023 07:48:41 AM UTC, original submission:  

The grohtml man page (as of a Sep 19, 2020 commit) has this item under Bugs, quoted here in its entirety:

"grohtml does not truly support hyphenation, but you can fool it into hyphenating long input lines, which can appear in HTML output with a hyphenated word followed by a space but no line break."

I find this sentence perplexing.  I asked about it on the mailing list a month ago (http://lists.gnu.org/r/groff/2023-07/msg00002.html), but no one responded, meaning no one else understood it either, or its meaning was so obvious no one wanted to waste their time on a reply.

The sentence makes a little more sense to me if I presume that a couple of the words are typos, and mentally edit it to: "...hyphenating long input WORDS, which can appear in HTML output AS a hyphenated word followed by a space..."

But even this does not clear up a couple of my questions:

  • What bug is being documented here?  (1) The act of fooling grohtml (i.e., you might inadvertently fool grohtml into doing this buggy thing), or (2) the lack of hyphenation, for which fooling grohtml is the workaround?  (My suspicion is (1), since HTML documents should never contain hyphenated words, but this isn't clear to me from this sentence, the only one in the man page that mentions hyphenation.)
  • How does one so fool grohtml?


As a possible source of illumination, I looked up the commit that added this sentence (051d5d5b), hoping its log entry might shed some light, but it did not.  In fact, nothing in the log even acknowledges any content changes, only style ones, yet the commit itself alters the content of both items in grohtml(1)'s Bugs section.  This is unusual enough for the typically comprehensive Branden log entry (and this one covers several less significant changes) that I wonder if those Bugs changes weren't intended to be in this commit at all, but snuck in with all the style changes.

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by gaius (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    No changes have been made to this item

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code