Date: Sat, 15 Jun 2002 03:53:12 +0300 From: Giorgos Keramidas <keramida@FreeBSD.org> To: Ross Lippert <ripper@eskimo.com> Cc: freebsd-doc@FreeBSD.org Subject: Re: Problem Report docs/31653 Message-ID: <20020615005312.GA21062@hades.hell.gr> In-Reply-To: <200206142313.QAA13634@eskimo.com> References: <20020520001522.GB3205@hades.hell.gr> <200206142313.QAA13634@eskimo.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--pWyiEgJYm5f9v55/ Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On 2002-06-14 16:13 -0700, Ross Lippert wrote: > > OK, I have finished the merge and I think I have a decent multimedia > chapter to replace chapter 14 (Sound) in the handbook. It is attached. Hello Ross & all, Sorry it has taken me so long to post a review to a chapter that was also Cc:'ed to me! First of all, thanks for letting me know the work on this was going on fine. I have taken the time to read through the chapter, paying attention to what was written. I am bound to have missed some details, but here's my short & quick review of it: : have been re-arrenged but the contents, remain the same. Thus : This author grouping is more like an editor grouping. : 7 June 2002 --> Comment pedantry: s/arrenged/arranged/ s/This author/this author/ : <para>With some willingness to experiment, FreeBSD can support : playback of video files and DVD's. The number of applications : to encode, re-encode, and playback various video media is more : limited than the number of sound applications. For example as Since I am not sure what 're-encode' is supposed to mean, I would probably write this as: "The number of applications to encode, convert, and playback various..." : limited than the number of sound applications. For example as : of this writing, there is no good transcoding application in the What is a 'transcoding application'? : <itemizedlist> : <listitem><para>How to configure your system so that your sound card is : recognized.</para></listitem> : <listitem><para>Methods to test that your card is working using : sample applications.</para></listitem> More whitespace would look great here. I like writing lists like the sample shown below. This makes future changes more easy to spot, and the original separation of the list in items is easier to visually grasp with one look: <itemizedlist> <listitem> <para>foo</para> <para>foo2</para> </listitem> <listitem> <para>bar</para> </listitem> <listitem> <para>baz</para> </listitem> </itemizedlist> : installed. XFree86 3.X may work, but this author has not made : the attempt.</para> Or any other author, for that matter. We don't want you to look like you're lazy, having taken the time to do all this work. Please, if you must write something about it, refer to XFree86 3.X with something like: XFree86 3.X may work, but it has not been tested with the what is described in this chapter. If you find that something described here does not work with XFree86 3.X please let us know. I would much prefer this part written like that. It is only a matter of PR (public relations, not problem reports), but it is important. : <para><emphasis>Warning:</emphasis> trying to mount an audio CD or : a video DVD with the <command>mount</command> command will result in an : error, at least, and a <emphasis>kernel panic</emphasis>, at : worst. These media have specialized encodings which differ from : the usual ISO-filesystem.</para> Don't use custom <emphasis>-based tags for notes like this. There is the <note> and <warning> container elements for stuff like this. Mark this up as shown below: <warning> <para>Trying to mount...</para> </warning> : <para>Video Payback is a very new and rapidly developing application s/Payback/playback/ : <para>Before you begin, you should know the model of the video : card you have and the chip it uses. While XFree86 supports a : wide variety of video cards, a much smaller number give good : playback performance. To obtain a list of extensions supported "While XFree86 supports a wide variety of video cards, very few of them give good..." : <para>It is a good idea to have a short MPEG file which can be : treated as a test file for evaluating various players and : options. Some DVD players default or are hardcoded to look for : DVD media in <filename>/dev/dvd</filename>, this it is a good : idea to use a symbolic links:</para> Which 'this'? Perhaps we need to change the text above to: Since some DVD players will look for DVD media in <filename>/dev/dvd</filename> by default, or have this device name hardcoded in them, you might find it useful to make this a symbolic link to the proper device:</para> <screen>... : <para>Additionally, DVD-decoding will require write permission on : the DVD devices.</para> "Note that DVD decoding..." (or is it "playback" here?) : <para>To enhance the shared memory X11 interface, it is : recommended that the values of some &man.sysctl.8; variables : should be increase: : </para> You should not leave whitespace before </para>. Also note that 'should be increase' is wrong here. : <indexterm><primary>sdl</primary></indexterm> : <indexterm><primary>SDL</primary></indexterm> : <indexterm><primary>dga</primary></indexterm> : <indexterm><primary>DGA</primary></indexterm> Do you really need to have these terms twice? : <para>Video display under X11 suffers from a multitude of : possibilities, what will really work is largely hardware : dependent. Each method described below will have varying "suffers from possibilities"? I am not a native speaker of English, and this might be an idiomatic expression that I have failed to learn, but I can't understand it. : <para> X11 : normal X11 output using shared memory</para> : <para> XVideo : an extension to the X11 : <para> SDL : the Simple Directmedia Layer</para> : <para> DGA : the Direct Graphics Access</para> : <para> SVGAlib : low level console graphics layer</para> Too much whitespace. You should a) remove all whitespace between the opening <para> tag and the content of the <para>...</para> element, and b) never, and I mean _never_, leave whitespace before ':', unless you're copy/pasting the output of a program. Thus: foo :this is the explanation . And a second sentence. is wrong, but foo: the explanation. And a second sentence. is ok. : through a special acceleration. This extension provides very : good quality playback on even low-end machines (for example my even on... : To check whether the extension is running, use <command>xvinfo</command>: : </para> The usual whitespace nit about </para>. : have a satisfying experience. You probably should read about : ways to improving performance in the advanced reading <xref ways of improving... ways in which you can improve... : <para>The SDL can be found at <filename role="package">sdl12</filename></para> devel/sdl12 not just sdl12. : <para>This section will discuss the software available from the No future tense please. "This section describes..." now and not later :) : <para>By <quote>experimental</quote>, I mean that you can expect : re-encoders, players, and DVD decrypters to all have some major s/to all have/to have/ : a short list of the sorts of things I mean:</para> s/sorts of/sort of/ : <listitem><para>A misuse of threads which causes a program to hang upon : completion than truly terminate.</para></listitem> s/than truly terminate/instead of truly terminating/ : Additionally, a number of options can be specified in the : <command>make</command> which echo at the start of the : build. : </para> The usual </para> whitespace stuff I like complaining about. : <para>If you have <filename : role="package">x11-toolkits/gtk12</filename> installed, then : you might as well enable to GUI. Otherwise, it is not worth ^^ the GUI. : MPlayer you must enable to DVD support option here ^^ the DVD... : <para>The HTML documentation to MPlayer is very informative. : If the reader finds the information on video hardware and : interfaces in thie chapter lacking, the MPlayer ^^^^ this chapter... : documentation is a very thorough alternative. I urge its : reading by anyone wishing to obtain expertise in Unix : video.</para> How about changing the last sentence to: You should definitely take the time to read the documentation of <application>MPlayer</application>, if you are looking for information about video support in UNIX. The original contains 'its reading' which sounds a bit strange to me. Of course, I could be wrong here. : home directory. to create this necessary subdirectory, ^^ capitalize this. : performance depends on many factors and will vary significantly : with hardware. : </para> The usual </para> whitespace stuff I like complaining about. : and <option>-framedrop</option> which helps performance. : </para> Ditto. Do the same to all the other </para> instances that match the regular expression: ^[[:space:]]*</para>[[:space:]]*$ : <para>Remember, if you are going to run as <username>root</username> : then set this in the <username>root</username> home directory as : well.</para> You can probably trim this off. It is implied, in the user configuration section above, since `root' is just another user. : MPEG and can be manipulated by the other packages discussed s/discussed/described/ : useful without the HTML. There are innummerable ways to : improve quality, lower bitrate, and change formats, and some : of these tricks may make the difference between good playback : performance and bad. "...between good or bad performance." : codec with MPEG3 audio encoding (<filename role="package"> : audio/lame</filename> is required):</para> Don't let whitespace creep inside <filename> elements please ;) : dump the title to a file and work on the file. : </para> wrap up </para>. : <para>The menus can then be used to open a file, or it can be : started to play a file immediately without the gui : with the command:</para> Is it "gui" or "GUI"? Choose one, and use it consistently. : role="package">graphics/transcode</filename>. Using a great : many options to the <command>make</command>. It's either "the <command>make</command> command" or "to <command>make</command>". The choise is yours. : <para>If you plan to install <filename : role="package">graphics/avifile</filename>, then add that : option:</para> : : <screen>&prompt.root; make WITH_AVIFILE=yes WITH_LIBMPEG2=yes</screen> Change the vague 'that' reference to: then add the <literal>WITH_AVIFILE</literal> option to your <command>make</command> command line, as shown here:</para> : <para>Finally, there are some other promising applications which : may become useful additions to the FreeBSD Ports Collection:</para> : <ulink url="http://avifile.sourceforge.net/">AVIFile</ulink>; which : is also a port <filename role='package'>graphics/avifile</filename>. Is it a port? (I know the answer, don't reply.) Because if it is, then there is no point in stating that it "may become a useful addition to the FreeBSD Ports" above. The same is true for all the rest of the ports mentioned at the end of this chapter. Pheww. This was a long one. Thanks for all the work you have put in making this chapter a reality. I sure do hope my comments won't put you off from making future contributions, or discourage you about this one. I am only trying to get the best results possible out, therefore take all the comments above with a grain of salt or many grains of salt. Whatever makes you feel better. Keep the good work coming :))) - Giorgos --pWyiEgJYm5f9v55/ Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.7 (FreeBSD) iD8DBQE9Co/31g+UGjGGA7YRArJWAJ0eco95qbam4pa/+qVuqx4GCyGLWwCfZPZ+ Q/m12o6NlktrSbLoB/dT82g= =9o9g -----END PGP SIGNATURE----- --pWyiEgJYm5f9v55/-- 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?20020615005312.GA21062>