Tcl Source Code

When built in html some man pages show wrong formatting of the ARGUMENTS section. There is indentation that should not be there.

Example in http://www.tcl.tk/man/tcl8.6/TclLib/FileSystem.htm
See section ARGUMENTS.
Starting at Tcl_PackageInitProc **proc1Ptr (out)  indentation is wrong.

I'm attaching a snapshot.

Merged to core-8-6-branch and up.

Thanks, françois, for taking this!

+1

After more thinking I decided to revert my originally proposed solution [ee40100bc1] and implement a very simple fix in [aee4bada42] consisting in enlarging a bit the width of Description Termes (dt) and Description Details (dd) items in Descripton Lists (dl). This does not suffer from the previously mentioned drawbacks and looks safer to me, and much simpler than diving into the nroff macros in man.macros and in the conversion code into html.

Snapshot attached ('with_aee4bada42.png').

I plan to merge soon. Any comments, anyone?

Note this fix is not perfect. If changes a bit the formatting of the man pages (further than fixing this bug), see the attached snapshot 'with-ee40100bc1.png'. The DD area is no longer exactly aligned with the DT area. Is this an issue? Probably not (the bug is worse IMO). Opinions?

Also my fix does not deal with the case of the first item in the .SH ARGUMENTS section, which still suffers from the bug described in the present ticket. Even knowing this, the fix is probably good enough. Going further would need to dive into the very old [1c115e499ef19779] that introduced the last change here.

I have found the issue.

First, the indentation problem appears in .AP directives within a .SH "ARGUMENTS" section. It only shows up when the size of the text to display before the first tab is larger than some limit. This can be demonstrated by shortening line 248 in FileSystem.3 from ".AP Tcl_PackageInitProc **proc1Ptr out" to, say, ".AP Tcl_type **pPtr out" and rebuilding the html man pages.

In principle one should be able to tune this limit using the .AS directive (see doc/man/macros): this would enlarge the area dedicated to displaying the .AP directive text, but it would only be a workaround. So let's forget about this possibility.

Analyzing the code generating the html man pages in tools/tcltk-man2html-utils.tcl one can see that .AP directives are translated into .IP in turn creating Definition Term (<DT>) and Definition Description (<DD>) tags. Each <DT> is preceded by a <P> paragraph tag.

What is wrong is that there is no closing tag </P>. The closing tag can be omitted in some cases (see the documentation about this, but it appears it's not the case when the <DT>... text wraps.

Hence the fix [ee40100bc1].

Well, not for me. When I generate the html man pages with core-8-6-branch (on Windows) I still see the problem. 

I'm seeing this with both MS Edge and Firefox on Windows.

This seems to have been resolved at some point.  Perhaps this report can be closed now.