[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: simplifying & enhancing kde manpages

On Thursday 15 April 2004 17:42, Nathaniel W. Turner wrote:
> On Tue, 27 Jan 2004 22:17:34 +0100 Achim Bohnet wrote:
> > My idea now was now to create a kde-options(?) manpage^Wsgml that describes
> > the generic kde and qt options (later maybe in more detail).   From all
> > other manpages just use a reference to this manpage.  
> 
> Have you made any progress on this?
> 
> This really does seem like the Right Way to document these options -- after 
> all, they are not provided by the applications themselves, but by kdelibs and 
> qt; it makes sense therefor, to put the documentation in the libs packages as 
> well.  If KDE adds (or worse, removes) an option to the common KDE options, 
> do we really want to have to update every individual application's manpage?  
> Would the individual app maintainers even notice something this subtle?
> 
> Anyway, nobody seemed to think this was a bad idea, so I guess I don't need to 
> try so hard to convince you.  =)
> 
> I'm willing to help with this, but of course I don't want to duplicate any 
> effort.
Hi Nathaniel,
Sorry for the late responce. 
I've not done much. Got sidetracked by docbook2man UTF-8 brain damage,
sgml, license problem ... :(  I'm MIA most of the time this year :(

Please feel free to take over.  I've attached 2 manpages Karolina send
to me and a modified copy of one of Chris's manpages with some additions
from qt3/doc/html/debug.html and kdecore/html/classKCmdLineArgs.html
I'm not sure if it's okay to c&p qts debug.html in a (L)GPL manpage.

Achim
> 
> Cheers,
> nate
-- 
  To me vi is Zen.  To use vi is to practice zen. Every command is
  a koan. Profound to the user, unintelligible to the uninitiated.
  You discover truth everytime you use it.
                                      -- reddy@lion.austin.ibm.com
--- Begin Message --- 
tisdagen den 27 januari 2004 22.17 you wrote:

> My idea now was now to create a
> kde-options(?) manpage^Wsgml that describes the generic kde and
> qt options (later maybe in more detail).   From all other manpages
> just use a reference to this manpage.    If possible one could
> even create templates in kdelibs-dev that are included and allow to
> change these generic parts of each kde manpage at a central
> place.


I once did this and man-pages to almost all KDE binaries in debian for KDE 3.1
Attached is my version, if it can be of any help.

Karolina

Attachment: kdelibs.kdeenviron
Description: Troff document

Attachment: kdelibs.kdeqtoptions
Description: Troff document


--- End Message ---
--- Begin Message --- 
torsdagen den 29 januari 2004 15.21 you wrote:

> Hi Karolina,
>
> great, especially the environment manpage!!  This was too only wish/todo
> list. IGood, that I updated to sarge last night instead of working on the
> manpages ;) 'll convert them to sgml and merge with stuff I already have. 
> Btw. there's not copyright notice.  Is LGPL okay?

That's ok.

Karolina

--- End Message ---
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@

    
	The docbook-to-man binary is found in the docbook-to-man package.
	Please remember that if you create the nroff version in one of the
	debian/rules file targets (such as build), you will need to include
	docbook-to-man in your Build-Depends control field.

  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Chris</firstname>">
  <!ENTITY dhsurname   "<surname>Cheney</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>January 28, 2004</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>ccheney@debian.org</email>">
  <!ENTITY dhusername  "Chris Cheney">
  <!ENTITY dhucpackage "<refentrytitle>KDE-OPTIONS</refentrytitle>">
  <!ENTITY dhpackage   "kde-options">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2002</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>standard command line options supported by almost every kde application</refpurpose>
  </refnamediv>
<!--
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>

      <arg><option><replaceable>Qt-options</replaceable></option></arg>
      <arg><option><replaceable>KDE-options</replaceable></option></arg>

    </cmdsynopsis>
  </refsynopsisdiv>
-->
  <refsect1>
    <title>DESCRIPTION</title>

    <para>Describes the standard options supported by almost every KDE application.
    The command line options of KDE programs follow the usual GNU command line
    syntax, with long options starting with two dashes (`-').  The list of standard
    command line options is included below.</para>

  </refsect1>
  <refsect1>
    <title>GENERIC OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term><option>--author</option>
        </term>
        <listitem>
          <para>Show author information.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--help</option>
        </term>
        <listitem>
          <para>Show help about options.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--help-all</option>
        </term>
        <listitem>
          <para>Show all options.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--help-kde</option>
        </term>
        <listitem>
          <para>Show KDE specific options.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--help-qt</option>
        </term>
        <listitem>
          <para>Show Qt specific options.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--license</option>
        </term>
        <listitem>
          <para>Show license information.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v</option>, <option>--version</option>
        </term>
        <listitem>
          <para>Show version information.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>STANDARD QT OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term><option>--bg</option>, <option>--background <replaceable>color</replaceable></option>
        </term>
        <listitem>
          <para>Sets the default background color and an application palette (light and dark shades are calculated).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--btn</option>, <option>--button <replaceable>color</replaceable></option>
        </term>
        <listitem>
          <para>Sets the default button color.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--cmap</option>
        </term>
        <listitem>
          <para>Causes the application to install a private color map on an 8-bit display.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--display <replaceable>displayname</replaceable></option>
        </term>
        <listitem>
          <para>Use the X-server display 'displayname'.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--dograb</option>
        </term>
        <listitem>
	  <para>Ignore any implicit or explicit --nograb. --dograb wins over
	  --nograb even when --nograb is last on the command line.  Running
	  under a debugger can cause an implicit --nograb, use --dograb to
	  override.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--fg</option>, <option>--foreground <replaceable>color</replaceable></option>
        </term>
        <listitem>
          <para>Sets the default foreground color.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--fn</option>, <option>--font <replaceable>fontname</replaceable></option>
        </term>
        <listitem>
          <para>Defines the application font.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--im <replaceable>XIMserver</replaceable></option>
        </term>
        <listitem>
          <para>Set XIM server.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--inputstyle <replaceable>inputstyle</replaceable></option>
        </term>
        <listitem>
          <para>Sets XIM (X Input Method) input style. Possible values are onthespot, overthespot, offthespot and root.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--name <replaceable>name</replaceable></option>
        </term>
        <listitem>
          <para>Sets the application name.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--ncols <replaceable>count</replaceable></option>
        </term>
        <listitem>
          <para>Limits the number of colors allocated in the color cube on an 8-bit display, if the application is using the QApplication::ManyColor color specification.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--nograb</option>
        </term>
        <listitem>
	  <para>Tells QT that the application should never grab the mouse or the keyboard.
	  This option is set by default when the program is running in the gdb debugger
	  under Linux. See also --dograb option.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--noxim</option>
        </term>
        <listitem>
          <para>Disable XIM.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--reverse</option>
        </term>
        <listitem>
          <para>Mirrors the whole layout of widgets.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--session <replaceable>sessionId</replaceable></option>
        </term>
        <listitem>
          <para>Restore the application for the given 'sessionId'.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--sync</option>
        </term>
        <listitem>
	  <para>Runs the application in X synchronous mode. Synchronous
	  mode forces the X server to perform each X client request
	  immediately and not use buffer optimization. It makes the
	  program easier to debug and often much slower. The --sync option
	  is only valid for the X11 version of Qt.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--title <replaceable>title</replaceable></option>
        </term>
        <listitem>
          <para>Sets the application title (caption).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--visual TrueColor</option>
        </term>
        <listitem>
          <para>Forces the application to use a TrueColor visual on an 8-bit display.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>STANDARD KDE OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term><option>--caption <replaceable>caption</replaceable></option>
        </term>
        <listitem>
          <para>Use 'caption' as name in the titlebar.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--config <replaceable>filename</replaceable></option>
        </term>
        <listitem>
          <para>Use alternative configuration file.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--dcopserver <replaceable>server</replaceable></option>
        </term>
        <listitem>
          <para>Use the DCOP Server specified by 'server'.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--geometry <replaceable>geometry</replaceable></option>
        </term>
        <listitem>
          <para>Sets the client geometry of the main widget.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--icon <replaceable>icon</replaceable></option>
        </term>
        <listitem>
          <para>Use 'icon' as the application icon.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--miniicon <replaceable>icon</replaceable></option>
        </term>
        <listitem>
          <para>Use 'icon' as the icon in the titlebar.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--nocrashhandler</option>
        </term>
        <listitem>
          <para>Disable crash handler, to get core dumps.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--style <replaceable>style</replaceable></option>
        </term>
        <listitem>
          <para>Sets the application GUI style.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--waitforwm</option>
        </term>
        <listitem>
          <para>Waits for a WM_NET compatible windowmanager.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>

    <title>SEE ALSO</title>

<!-- FIXME: cut and paste the examples from the api docs -->
    <para>"Detailed Description" section in the Documentation of KDE C++ class
    KCmdLineArgs of the kdecore library.</para>
  </refsect1>
  <refsect1>

    <title>AUTHOR</title>

    <para>This manual page was written by &dhusername; &lt;&dhemail;&gt; for
      the &debian; system (but may be used by others).  Permission is
      granted to copy, distribute and/or modify this document under
      the terms of the <acronym>GNU</acronym> Free Documentation
      License, Version 1.1 or any later version published by the Free
      Software Foundation; with no Invariant Sections, no Front-Cover
      Texts and no Back-Cover Texts.</para>

  </refsect1>
</refentry>

<!--

Text partly taken from:
	qt3/doc/html/debug.html
	kdecore/html/classKCmdLineArgs.html

-->

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Reply to: