New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

indentation in code examples is lost #21

Closed
reinerh opened this Issue Jan 18, 2017 · 4 comments

Comments

Projects
None yet
2 participants
@reinerh

reinerh commented Jan 18, 2017

Some manpages have source code examples, like scanf(3).
The generated HTML page loses the indentation, which doesn't look very nice.

@stapelberg

This comment has been minimized.

Show comment
Hide comment
@stapelberg

stapelberg Jan 18, 2017

Contributor

Thanks for the report.

Manpage rendering is done by mandoc(1).

The indentation is present when rendering to stdout:

$ curl https://manpages.debian.org/jessie/manpages-dev/scanf.3.en.gz | mandoc
[…]
EXAMPLE
       To use the dynamic allocation conversion specifier, specify m as a
       length modifier (thus %ms or %m[range]).  The caller must free(3) the
       returned string, as in the following example:

           char *p;
           int n;

…but not when rendering to HTML:

$ curl https://manpages.debian.org/jessie/manpages-dev/scanf.3.en.gz | mandoc -Thtml
[…]
<h1>EXAMPLE</h1> To use the dynamic allocation conversion specifier, specify <b>m</b> as a length modifier (thus <b>%ms</b> or  <b>%m[</b><i>range</i><b>]</b>). The caller must <b>free</b>(3) the returned string, as in the following example:<br/>
<div class="spacer">
</div>
<br/>
char *p;<br/>
int n;<div class="spacer">
</div>
<br/>
errno = 0;<br/>
n = scanf(&quot;%m[a-z]&quot;, &amp;p);<br/>
if (n == 1) {<br/>
    printf(&quot;read: %s\n&quot;, p);<br/>
    free(p);<br/>
} else if (errno != 0) {<br/>
    perror(&quot;scanf&quot;);<br/>
} else {<br/>
    fprintf(stderr, &quot;No matching characters\n&quot;);<br/>
}<br/>
<br/>
<div class="spacer">
</div>
As shown in the above example, it is necessary to call <b>free</b>(3) only if the <b>scanf</b>() call successfully read a string.</div>
<div class="section">

This is reproducible with the mandoc version in Debian testing (1.13.3-3), and with a CVS checkout from yesterday.

Would you like to report this issue upstream? If you’d prefer, I could do that for you.
See http://mdocml.bsd.lv/ for the upstream website.

Contributor

stapelberg commented Jan 18, 2017

Thanks for the report.

Manpage rendering is done by mandoc(1).

The indentation is present when rendering to stdout:

$ curl https://manpages.debian.org/jessie/manpages-dev/scanf.3.en.gz | mandoc
[…]
EXAMPLE
       To use the dynamic allocation conversion specifier, specify m as a
       length modifier (thus %ms or %m[range]).  The caller must free(3) the
       returned string, as in the following example:

           char *p;
           int n;

…but not when rendering to HTML:

$ curl https://manpages.debian.org/jessie/manpages-dev/scanf.3.en.gz | mandoc -Thtml
[…]
<h1>EXAMPLE</h1> To use the dynamic allocation conversion specifier, specify <b>m</b> as a length modifier (thus <b>%ms</b> or  <b>%m[</b><i>range</i><b>]</b>). The caller must <b>free</b>(3) the returned string, as in the following example:<br/>
<div class="spacer">
</div>
<br/>
char *p;<br/>
int n;<div class="spacer">
</div>
<br/>
errno = 0;<br/>
n = scanf(&quot;%m[a-z]&quot;, &amp;p);<br/>
if (n == 1) {<br/>
    printf(&quot;read: %s\n&quot;, p);<br/>
    free(p);<br/>
} else if (errno != 0) {<br/>
    perror(&quot;scanf&quot;);<br/>
} else {<br/>
    fprintf(stderr, &quot;No matching characters\n&quot;);<br/>
}<br/>
<br/>
<div class="spacer">
</div>
As shown in the above example, it is necessary to call <b>free</b>(3) only if the <b>scanf</b>() call successfully read a string.</div>
<div class="section">

This is reproducible with the mandoc version in Debian testing (1.13.3-3), and with a CVS checkout from yesterday.

Would you like to report this issue upstream? If you’d prefer, I could do that for you.
See http://mdocml.bsd.lv/ for the upstream website.

@reinerh

This comment has been minimized.

Show comment
Hide comment
@reinerh

reinerh Jan 18, 2017

Thanks for clarifying that the pages are generated with mandoc.
I just had a look at the current upstream version and noticed that this is already known and on their TODO list.

reinerh commented Jan 18, 2017

Thanks for clarifying that the pages are generated with mandoc.
I just had a look at the current upstream version and noticed that this is already known and on their TODO list.

@reinerh reinerh closed this Jan 18, 2017

bob-beck pushed a commit to openbsd/src that referenced this issue Jan 26, 2017

Fix -man -Thtml formatting after .nf (which has nothing to do
with "literal", by the way, it means "no fill"):

* Use <pre> such that whitespace is preserved.
* Preserve lines breaks.
* For font alternating macros, avoid node recursion which required
scary juggling with the fill state.  Instead, simply print the text
children directly.

Missing feature first noticed by kristaps@ in 2011,
the again reported by afresh1@ in 2016,
and finally reported here: Debian/debiman#21 ,
which i only found because of Shane Kerr's comment here:
https://plus.google.com/110314300533310775053/posts/H1eaw9Yskoc
@stapelberg

This comment has been minimized.

Show comment
Hide comment
@stapelberg

stapelberg Jan 26, 2017

Contributor

This has been fixed upstream. Re-opening this issue to track the rollout of the new version to manpages.d.o.

Contributor

stapelberg commented Jan 26, 2017

This has been fixed upstream. Re-opening this issue to track the rollout of the new version to manpages.d.o.

@stapelberg stapelberg reopened this Jan 26, 2017

stapelberg added a commit that referenced this issue Jan 27, 2017

Update goldens and stylesheet for newer mandoc version
<div class="mandoc"> is no longer present since
http://mdocml.bsd.lv/cgi-bin/cvsweb/man_html.c.diff?r1=1.125&r2=1.126

<div class="spacer"> is called <div class="Pp"> since
http://mdocml.bsd.lv/cgi-bin/cvsweb/html.c.diff?r1=1.197&r2=1.198

A couple of other cosmetic HTML changes required updating the golden
files (e.g. changes in whitespace and additional HTML class names).

related to #21
@stapelberg

This comment has been minimized.

Show comment
Hide comment
@stapelberg

stapelberg Jan 28, 2017

Contributor

This is now live.

Contributor

stapelberg commented Jan 28, 2017

This is now live.

@stapelberg stapelberg closed this Jan 28, 2017

hakrdinesh pushed a commit to hakrtech/openbsd-src0-test that referenced this issue Jan 17, 2018

Fix -man -Thtml formatting after .nf (which has nothing to do
with "literal", by the way, it means "no fill"):

* Use <pre> such that whitespace is preserved.
* Preserve lines breaks.
* For font alternating macros, avoid node recursion which required
scary juggling with the fill state.  Instead, simply print the text
children directly.

Missing feature first noticed by kristaps@ in 2011,
the again reported by afresh1@ in 2016,
and finally reported here: Debian/debiman#21 ,
which i only found because of Shane Kerr's comment here:
https://plus.google.com/110314300533310775053/posts/H1eaw9Yskoc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment