Date: Mon, 3 Jun 2002 08:07:03 +0200 From: Udo Erdelhoff <ue@nathan.ruhr.de> To: freebsd-doc@freebsd.org Subject: Re: A video chapter (pr doc/31653) Message-ID: <20020603060702.GO65310@nathan.ruhr.de> In-Reply-To: <200206020301.UAA09990@eskimo.com> References: <200206020301.UAA09990@eskimo.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Hi Ross, On Sat, Jun 01, 2002 at 08:01:52PM -0700, Ross Lippert wrote: > I have a video chapter I would like to submit to deal the lack of > anything about video under freebsd, which is the pr in the subject > line. I have read your chapter as far as possible and it looks good. The only problem is the fact that somebody or something cut it off, your mail ends in the middle of a sentence. To quote: > creates an MPEG video file (which is a very portable video format > compared to the various AVI formats Additionally, something replaced the '&' characters in the article with &. > I am new to the doc project and I'd like to have some guidance as to > how to submit it, and get some people to look at it and give me > pointers on style and docproj fine-points. I'm attaching it below. Well, posting it here is one of two good ways of submitting it. The other would be a followup to the PR, either with the new chapter or with an URL to it. > Specifically, I need advice on which commands are appropriate to > man-entity-ify and wwhich ones are not. I don't know much about what > the rationale is behind man-entities in the handbook sgml. Do 'we' have a clear-cut rationale on the use of the man page entities? There are a number of conflicting styles, some people like to use the entities as often as possible; other prefer to avoid repetitions within a chapter. Other than that: - I would suggest to call this chapter 'Video Playback', not just 'Video'. A video chapter should deal with stuff like configuring your card (i.e. the general stuff). - Please try to reduce the number of footnotes and stuff in brackets. - <screen>, <programlisting>, <*list> etc. should be outside of <para>s, not inside - Try to avoid sentences cut in half by <programlisting> and similar entities. Complete your sentence before the block. > [...] Also, setting the &man.sysctl.1; variables as below > <programlisting>kern.ipc.shmmax=67108864 > kern.ipc.shmall=32768</programlisting> > to enhance the shared memory X11 interface. > </para> This version looks better: ] To enhance the settings for the X11 shared memory interface, the ] values of some &man.sysctl.1; need to be changed. Some reasonable ] values are:</para> ] ] <programlisting>kern.ipc.shmmax=67108864 ] kern.ipc.shmall=32768</programlisting> Or something to that effect. - I have noticed a few formatting snafus like </screen>, </para>, and similar not snuggling up to their content. - Please do not use UN*X, we are not that paranoid anymore. - You have managed to avoid contractions almost completly, which is A Good Thing(tm). Please remove the remaining ones, that should also help with the "it is" vs. "it's" vs. "its" problems. You have also put two spaces behind every full stop in almost all cases, another good thing. - Some additional hints on style can be found in the FDP. All in all, good stuff. /s/Udo -- Windows is not the answer, Windows is the question. No is the answer. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020603060702.GO65310>