[MPlayer-DOCS] General documentation propositions
Torinthiel
torinthiel at megapolis.pl
Thu Dec 21 10:31:15 CET 2006
I have some propositions for changing the XML documentation markup:
1) There are some places (I've found three, two in codec importing HOWTO
and one in FAQ) where we refer to menu items. In one places these are
already marked with <guimenu>, <guisubmenu> and <guimenuitem>, which is
good, because it differentiates them visually in HTML output. I'd do the
same to rest, and one step further: DocBook has a tag <menuchoice>,
which, when presented with a series of those tags renders them as
menu->submenu->submenu->menuitem, i.e. almost he same as now (the only
differences are spaces around ->). On the plus side is better structural
markup, and possibility to change it in one go. Also, the menuchoice can
contain <shortcut> which in turn contains keyboard shortcuts for the
selected menu items. On the minus side is a bit more text in sources.
See menuchoice.patch (and maybe I'll add <shortcut> and any more menus
I'll find)
2) As for keyboard shortcuts, we use <keycap> and for more keys
something like <keycap>Ctrl</keycap>+<keycap>F</keycap>.
The DocBook syntax for this is
<keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo>. As above,
it provides better structural markup, and renders a bit different, as
Ctrl-F (I like that form more, to be honest). It can be made to render
Ctrl+F, but that requires <keycombo action="simul">, which is a bit too
verbose for my taste.
Anyway, see keycombo.patch, these are all key combinations in docs. It
also changes one CTRL+ALT... to Ctrl+Alt..., for consistency.
3) I'd hunt down and change <simpara> to <para> whenever possible, just
because I like <para> more. There are places where <simpara> is
necessary, but far less then present now.
4) faq.html (and the FAQ in single HTML) somehow is wider than the
browser, while all other parts are not. I'll look into this and try
to fix.
OK to proceed?
Torinthiel
--
Waclaw "Torinthiel" Schiller GG#: 3073512
torinthiel(at)megapolis(dot)pl
gpg: 0906A2CE fpr: EE3E DFB4 C4D6 E22E 8999 D714 7CEB CDDC 0906 A2CE
"No classmates may be used during this examination"
-------------- next part --------------
Index: codecs.xml
===================================================================
--- codecs.xml (revision 21709)
+++ codecs.xml (working copy)
@@ -669,7 +671,7 @@
Start <command>regedit</command>.
</para></step>
<step><para>
- Press <keycap>Ctrl</keycap>+<keycap>F</keycap>, disable the first two
+ Press <keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo>, disable the first two
checkboxes, and enable the third. Type in the fourcc of the codec (e.g.
<userinput>TM20</userinput>).
</para></step>
Index: video.xml
===================================================================
--- video.xml (revision 21709)
+++ video.xml (working copy)
@@ -581,8 +581,9 @@
</simpara></listitem>
<listitem><simpara>
Some drivers simply fail to switch back to normal resolution (use
- <keycap>Ctrl</keycap>+<keycap>Alt</keycap>+<keycap>Keypad +</keycap> and
- <keycap>Ctrl</keycap>+<keycap>Alt</keycap>+<keycap>Keypad -</keycap>
+ <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Keypad +</keycap></keycombo>
+ and
+ <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Keypad -</keycap></keycombo>
to switch back manually).
</simpara></listitem>
<listitem><simpara>
@@ -1288,8 +1289,8 @@
<listitem><simpara>
Often after terminating VESA driver you get
<emphasis role="bold">black</emphasis> screen. To return your screen to
- original state - simply switch to other console
- (by pressing <keycap>Alt</keycap>+<keycap>F<x></keycap>)
+ original state - simply switch to other console (by pressing
+ <keycombo><keycap>Alt</keycap><keycap>F<x></keycap></keycombo>)
then switch to your previous console by the same way.
</simpara></listitem>
<listitem><simpara>
@@ -1334,9 +1335,9 @@
<listitem><simpara>
With XFree86 3.x.x: you have to cycle through available resolutions
with the
- <keycap>Ctrl</keycap>+<keycap>Alt</keycap>+<keycap>Keypad +</keycap>
+ <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Keypad +</keycap></keycombo>
and
- <keycap>Ctrl</keycap>+<keycap>Alt</keycap>+<keycap>Keypad -</keycap>
+ <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Keypad -</keycap></keycombo>
keys.
</simpara></listitem>
</itemizedlist>
@@ -2315,7 +2316,7 @@
--></screen>
(If you use X, now change to matroxfb with for example
- <keycap>Ctrl</keycap>+<keycap>Alt</keycap>+<keycap>F1</keycap>.)
+ <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo>.)
Change <literal>640</literal> and <literal>512</literal> if you set
the resolution to other...
</para></step>
@@ -2488,7 +2489,8 @@
the following parameters on the kernel command line:
<option>append="video=vesafb:ywrap,mtrr" vga=791</option>.
You should start <application>X</application>, then switch to console mode
- with e.g. <keycap>CTRL</keycap>+<keycap>ALT</keycap>+<keycap>F1</keycap>.
+ with e.g.
+ <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo>.
If you fail to start <application>X</application> before running
<application>MPlayer</application> from the console, the video
becomes slow and choppy (explanations are welcome).
@@ -2497,8 +2499,8 @@
<screen>clear; mplayer -vo fbdev -zoom -cache 8192 dvd://</screen>
Now you should see the movie running in console mode filling up about
- half your laptop's LCD screen.
- To switch to TV hit <keycap>Fn</keycap>+<keycap>F5</keycap> three times.
+ half your laptop's LCD screen. To switch to TV hit
+ <keycombo><keycap>Fn</keycap><keycap>F5</keycap></keycombo> three times.
Tested on a Tecra 8000, 2.6.15 kernel with vesafb, ALSA v1.0.10.
</para></listitem>
<listitem>
-------------- next part --------------
Index: codecs.xml
===================================================================
--- codecs.xml (revision 21709)
+++ codecs.xml (working copy)
@@ -635,7 +635,9 @@
Start <command>graphedit.exe</command>.
</para></step>
<step><para>
- From the menu select Graph -> Insert Filters.
+ From the menu select
+ <menuchoice><guimenu>Graph</guimenu>
+ <guisubmenu>Insert Filters</guisubmenu></menuchoice>.
</para></step>
<step><para>
Expand item <systemitem>DirectShow Filters</systemitem>.
@@ -681,8 +683,8 @@
Now that you have the file, we need the GUID. Try searching again, but
now search for the codec's name, not the fourcc. Its name can be acquired
when Media Player is playing the file, by checking
- <guimenu>File</guimenu> -> <guisubmenu>Properties</guisubmenu> ->
- <guimenuitem>Advanced</guimenuitem>.
+ <menuchoice><guimenu>File</guimenu> <guisubmenu>Properties</guisubmenu>
+ <guimenuitem>Advanced</guimenuitem></menuchoice>.
If not, you are out of luck. Try guessing (e.g. search for TrueMotion).
</para></step>
<step><para>
Index: faq.xml
===================================================================
--- faq.xml (revision 21709)
+++ faq.xml (working copy)
@@ -389,7 +389,9 @@
Are you using FVWM? Try the following:
<orderedlist>
<listitem><para>
- Start -> Settings -> Configuration -> Base Configuration
+ <menuchoice><guimenu>Start</guimenu><guisubmenu>Settings</guisubmenu>
+ <guisubmenu>Configuration</guisubmenu>
+ <guimenuitem>Base Configuration</guimenuitem></menuchoice>
</para></listitem>
<listitem><para>
Set <systemitem>Use Applications position hints</systemitem>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/mplayer-docs/attachments/20061221/975b9805/attachment.pgp>
More information about the MPlayer-DOCS
mailing list