From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp1.rz.uni-karlsruhe.de (Debian-exim@smtp1.rz.uni-karlsruhe.de [129.13.185.217]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o72KvDMf016524 for ; Mon, 2 Aug 2010 16:57:15 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by smtp1.rz.uni-karlsruhe.de with esmtp (Exim 4.63 #1) id 1Og24N-0002pu-Lz; Mon, 02 Aug 2010 22:57:11 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.71) (envelope-from ) id 1Og24N-0000yl-L0 for discuss@mdocml.bsd.lv; Mon, 02 Aug 2010 22:57:11 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1Og24N-0004a5-K2 for discuss@mdocml.bsd.lv; Mon, 02 Aug 2010 22:57:11 +0200 Received: from schwarze by usta.de with local (Exim 4.71) (envelope-from ) id 1Og24N-0001er-CF for discuss@mdocml.bsd.lv; Mon, 02 Aug 2010 22:57:11 +0200 Date: Mon, 2 Aug 2010 22:57:11 +0200 From: Ingo Schwarze To: discuss@mdocml.bsd.lv Subject: Re: mdoc.7 tweaks Message-ID: <20100802205711.GA7805@iris.usta.de> References: <20100802190029.GA20950@bramka.kerhand.co.uk> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20100802190029.GA20950@bramka.kerhand.co.uk> User-Agent: Mutt/1.5.20 (2009-06-14) Hi Jason, first, many thanks for ploughing through this really large manual! Jason McIntyre wrote on Mon, Aug 02, 2010 at 08:00:05PM +0100: > this page makes my head hurt ;( We hope to change that ASAP... It is already a better manual than we had before, and it is supposed to become a good manual. ;-) > i cannot do a diff for too many things here, so this diff: Right, let's try to work with diffs of manageable size, not mixing too many unrelated things. > *) corrects a few obvious mistakes > *) adopts some of the changes i proposed for man(7) > *) tries to cut down just a little on the awful tendency to stick > a hyphen between two words. Everything not related to .Sx / .Sy is ok schwarze@. > *) uses Sy for macros instead of Sx. we could use something else but > not, please, Sx. Hmm, i'm not sure. Using exactly Sx (and not anything else) has a point. On http://mdocml.bsd.lv/mdoc.7.html , you can easily navigate the whole manual using the macro hyperlinks. I know that is irrelevant for man(1), and for terminal output in general, but it may still be considered useful. Of course, we can decide against hyperlinking, but do we really want to make that decision in a hurry, right now, after release soft lock, and while Kristaps is not around? When the choice of what to use instead is not even obvious? > *) uses Sx for section names. I don't think i agree with that item. Let's take the first example from the top of the file: > The first section (sections are denoted by > -.Sx \&Sh ) > -must be the NAME section, consisting of at least one > -.Sx \&Nm > +.Sy \&Sh ) > +must be the > +.Sx NAME > +section, consisting of at least one > +.Sy \&Nm > followed by > -.Sx \&Nd . > +.Sy \&Nd . > .Pp What is the hyperlink from NAME supposed to point to? Logically, it should point to the explanation of the NAME section, which is here: The sections in an .Nm document are conventionally ordered as they appear above. Sections should be composed as follows: .Bl -ohang -offset Ds .It Sx NAME The name(s) and a one line description of the documented material. But it won't point there, because the ".It NAME" is not an ".Ss NAME". And even if it were, the .Sx reference would be ambiguous, because mdoc(7) of course has its proper ".Sh NAME" section, which comes before anything else. That's where the hyperlink will point - which makes very little sense, because we are not talking about the NAME section of the mdoc(7) manual, but about the syntax and semantics of NAME sections in general. It gets even worse. Look here: > +.It Sx EXIT STATUS > +This section documents the > +command exit status for section 1, 6, and 8 utilities. This is a dangling, invalid hyperlink. The mdoc(7) manual has no EXIT STATUS section, so we cannot point to it. On the other hand, there were a few valid internal references which you have mangled. I think the following are correct as they stand and shouldn't be changed: macro is a -.Sx Block full-implicit +.Sy Block full-implicit macro only when invoked as the first macro in a .Ss Block partial-implicit Like block full-implicit, but with single-line scope closed by -.Sx Reserved Characters +.Sy Reserved Characters or end of line. @@ -1477,7 +1478,7 @@ which signifies the current manual revision date dictated by .Xr cvs 1 , or instead a valid canonical date as specified by -.Sx Dates . +.Sy Dates . If a date does not conform or is empty, the current date is used. .Pp Examples: macro uses -.Sx Block full-implicit +.Sy Block full-implicit semantics when invoked as the first macro on an input line in the .Em SYNOPSIS section; otherwise, it uses ordinary -.Sx In-line +.Sy In-line semantics. @@ -2627,15 +2634,15 @@ .Em SYNOPSIS section, in which case a variable name is also specified. Note that it accepts -.Sx Block partial-implicit +.Sy Block partial-implicit syntax when invoked as the first macro in the .Em SYNOPSIS section, else it accepts ordinary -.Sx In-line +.Sy In-line syntax. .It groff behaves irregularly when specifying .Sq \ef -.Sx Text Decoration +.Sy Text Decoration within line-macro scopes. mandoc follows a consistent system. > one issue: formatting the page with groff: > > mdoc.7:773: warning: can't find special character `lb' > mdoc.7:773: warning: can't find special character `rb' > > and the offending text: > > \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb That seems easy; i guess it's a typo, and i would just change lb to lB and rb to rB, like this: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB > anyway, this is a start. Yes, indeed, and thanks again for attacking this. Thus, i don't really like asking the following question: Are you really sure we should switch from .Sx to .Sy right now? If yes, we need to get it right at once, including choosing the macro we really want, but i do not want to digress into .Sy vs. .Ic vs. whatever bikeshedding as long as we do not even agree that we need to get rid of .Sx at all. If no, will you pull the .Sx/.Sy parts out of the diff for now, or shall i do it? Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv