Hi David, David Walker wrote on Thu, Oct 13, 2011 at 04:01:22AM +1030:
> I'm looking at cvs and man pages and stuff. > > I notice that two cvs pages - cvs(1) and cvs(5) - don't have SEE ALSO > hyperlinks appearing in cgi ... > > http://www.openbsd.org/cgi-bin/ \ > man.cgi?query=cvs&sektion=1&manpath=OpenBSD+Current > > http://www.openbsd.org/cgi-bin/ \ > man.cgi?query=cvs&sektion=5&manpath=OpenBSD+Current > > ... so I browse mdoc But cvs(1) manual source code is written in the man(7) language, not in the mdoc(7) language. > and see this: > > Xr > Link to another manual ... > > .Xr name section > > If > section is followed by non-punctuation, an Ns is inserted into the token > stream. The man(7) code in cvs(1) looks like this: .BR ci ( 1 ), .BR co ( 1 ), ... That's about as good as it gets with man(7). Indeed, man.cgi doesn't seem to recognize that as manual crossreferences, for whatever reason. But don't waste your time on man.cgi, i hope to replace it with mandoc.cgi in a few months from now, see http://mdocml.bsd.lv/mandoc-tools/ . > ... and think I'm not used to seeing punctuation after the last link > which the two offending man pages have (one has a punctuation which > probably isn't good at any rate). Yes, the trailing punctuation after the last item is neither needed nor nice. > So I check against a 5.0 snapshot and the pages square with cgi, viz. > the SEE ALSO is formatted differently on the operating system from > what I'm used to. > Take mdoc and afterboot as examples, they both have cgi hyperlinks and > the OS pages are what I'm used to. > > So I'd like to look at that and the place to start is src ... That's the right idea, yes. > http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/cvs/cvs.1?rev=1.127 > http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/cvs/cvs.5?rev=1.8 But that's not the right sources. You are looking at OpenCVS (src/usr.bin/cvs), which is unfinished alpha-quality software. Unfortunately, the OpenCVS maintainers ran away before finishing their job. People are welcome to pick up OpenCVS development, but it is a hard job, definitely not for beginners. So, we are still forced to use GNU CVS (src/gnu/usr.bin/cvs), and that's what is installed and contained in the snapshots and releases. > ... where I run into other issues. > Those man pages are quite different to what I see on the OS and on the web. > I readily accept there might be build processes I'm not looking at but > is this correct? No, it has nothing to do with the build process, it's just a different program. > One difference I'm particularly curious about is the presence of > cvsintro.7 both as a file in > http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/cvs/ and referred to > in the previous cvs files but if I'm looking in the wrong place that > would make a lot of sense. > > Of minor note also is the "page demarcations" on the cgi and the OS, > which looks like it's done by Dt, is in lowercase on cvs(5) which is a > clear violation of the rules. :] No, that's not .Dt, but man(7) .TH. Yes, the lower case in cvs(5) .TH slightly violates conventions. > As I apparently can't find the source, however, src/gnu/usr.bin/cvs/man/ > I can't think about fixing this. GNU cvs(1) is maintained upstream, http://savannah.nongnu.org/projects/cvs So if you prepare patches, prepare them against the current upstream version, and send them upstream. We don't patch minor glitches away in upstream documentation in OpenBSD, it just makes synching harder. (We do of course fix major factual errors that could cause problems to users.) > I love to be clued in on how this works or correct source for those pages ... > Regardless, in terms of formatting, there's an inconsistency between > those two man pages and other man pages as they appear on a console > which I guess is at least worth noting. Yes, man(7) documents always look slightly different when compared to mdoc(7) documents. Yours, Ingo
