Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 17 Sep 2020 13:54:59 +0200
From:      Michael Gmelin <freebsd@grem.de>
To:        Wolfram Schneider <wosch@freebsd.org>
Cc:        Kurt Jaeger <pi@freebsd.org>, "freebsd-ports@freebsd.org" <freebsd-ports@freebsd.org>
Subject:   Re: How do port man pages get into https://www.freebsd.org/cgi/man.cgi?
Message-ID:  <18642207-FA26-47F6-9F2E-9ABCA9306240@grem.de>
In-Reply-To: <CAMWY7CCEsiHhVBnJH%2Bu2TtaEk1fLFi5Yh3uvjJxzf20626M=mg@mail.gmail.com>
References:  <CAMWY7CCEsiHhVBnJH%2Bu2TtaEk1fLFi5Yh3uvjJxzf20626M=mg@mail.gmail.com>

next in thread | previous in thread | raw e-mail | index | archive | help
Hi Wolfram,

> On 17. Sep 2020, at 11:44, Wolfram Schneider <wosch@freebsd.org>
> wrote:
>=20
> =EF=BB=BFOn Wed, 16 Sep 2020 at 20:34, Michael Gmelin <freebsd@grem.de> w=
rote:
>>=20
>> @Wolfram: Do you think you could look into this (paperless man
>> page). Thanks!
>=20
> the page https://man.freebsd.org/paperless
>=20
> looks fine for me. What are you missing?
>=20

When I checked yesterday, it just returned an empty page (I only tried
once though).

Today it shows up, but it has some serious[0] rendering issues (starting
at about "Install and configure uwsgi"), which are probably caused by
misinterpreting '\\"' at the end of line 135 of the man page.

It renders fine using man(1) on the console (which uses mandoc(1)) and
also when converting it to html using `mandoc -T html'.

`mandoc -T lint' is also happy with the man page.

`groff -T html -man' does complain though, shows these issues at
line 135:

<standard input>:135: a space character is not allowed in an escape name
<standard input>:135: warning: numeric expression expected (got `u')
<standard input>:135: warning: can't find font `['

and creates output like the one seen on man.freebsd.org.

Based on this, I assume that man.cgi uses groff or a similar tool and
not mandoc to create html output.

I'll change literal parts of the paperless man page later today, so that
examples render nicer using `mandoc -T html', which will also fix groff
output as a side-effect by getting rid of the offending escape
sequence. I'll bump the revision and hope that it will be picked up
sooner or later.

Since we switched to mandoc(1) being the default for man(1) in HEAD
more than five years ago, I think it would make sense to do the same
for man.cgi to keep things consistent. QA is usually done
using mandoc -T lint for syntax, igor for style, and by checking
manually on the console, none of which would have revealed that problem
(not just for ports, but also in base).

Adapting the style sheet shouldn't be too hard. I'm happy to help with
that, if needed.

Thanks
Michael

[0]Serious in the sense that relevant information is lost.

> -Wolfram
>=20
>=20
>> -m
>>=20
>>>> On 1. Sep 2020, at 11:55, Michael Gmelin <freebsd@grem.de> wrote:
>>>=20
>>> =EF=BB=BF
>>>=20
>>>> On Mon, 31 Aug 2020 20:33:34 +0200
>>>> Wolfram Schneider <wosch@freebsd.org> wrote:
>>>>=20
>>>>> On Wed, 26 Aug 2020 at 18:50, Kurt Jaeger <pi@freebsd.org> wrote:
>>>>>=20
>>>>> Hi!
>>>>>=20
>>>>>>> man.cgi has provisions for most of this already, it's only
>>>>>>> missing some job to regulary extract the latest
>>>>>>>=20
>>>>>>> ftp://ftp.freebsd.org/pub/FreeBSD/snapshots/amd64/13.0-CURRENT/port=
s.txz
>>>>>>>=20
>>>>>>> for the current tree of the manuals.
>>>>>>=20
>>>>>> How does it actually create the pages though?
>>>>>=20
>>>>> wosch probably knows this.
>>>>=20
>>>> Indeed ;-)
>>>=20
>>> Thanks!
>>>=20
>>>>=20
>>>> The ports manual pages will be updated once when a new release
>>>> comes out. Maybe every 3-9 months. The update takes hours and a
>>>> lot of resources (60GB download of all packages and unpacking).
>>>>=20
>>>=20
>>> It would be cool if you could share the scriptwork that does this.
>>> Getting to a higher update frequency for ports would be really
>>> useful, but it feels like that this will require coordination
>>> between different teams/individuals.
>>>=20
>>>> -Wolfram
>>>=20
>>> Do you have any idea why the man page below isn't included?
>>>=20
>>>>>> E.g., the
>>>>>> man page paperless(7) created by deskutils/py-paperless [0] still
>>>>>> isn't available over man.cgi, even though the port was created a
>>>>>> long time before 12.1 was released and is in 12.1's ports.txz.
>>>=20
>>> Cheers,
>>> Michael
>>>=20
>>> --
>>> Michael Gmelin
>>> _______________________________________________
>>> freebsd-ports@freebsd.org mailing list
>>> https://lists.freebsd.org/mailman/listinfo/freebsd-ports
>>> To unsubscribe, send any mail to
>>> "freebsd-ports-unsubscribe@freebsd.org"
>>=20
>=20
>=20
> --=20
> Wolfram Schneider <wosch@FreeBSD.org> https://wolfram.schneider.org



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?18642207-FA26-47F6-9F2E-9ABCA9306240>