brl/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

man: Use asciidoc for main man page as well

Browse Source 
We already use asciidoc for the gnome-extensions man page, while
the main man page is generated from docbook XML. The former is a
much friendlier source format, so use it for both man pages.

Hopefully the plain text format encourages updates, to prevent the
page from getting as badly out of sync again as it is currently.

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/1553>
This commit is contained in:
Florian Müllner 2020-12-27 23:46:57 +01:00
parent 1989a2f9f9
commit 3fc5c4c180
5 changed files with 111 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
man/gnome-shell.txt Normal file
View File

@ -0,0 +1,81 @@
GNOME-SHELL(1)
=============
:man manual: User Commands
:man source: GNOME-SHELL
:doctype: manpage
:date: December 2020
NAME
----
gnome-shell - Graphical shell for the GNOME desktop
SYNOPSIS
--------
*gnome-shell* ['OPTION'...]
DESCRIPTION
-----------
GNOME shell provides core user interface functions for the GNOME 3 desktop,
like switching to windows and launching applications. GNOME shell takes
advantage of the capabilities of modern graphics hardware and introduces
innovative user interface concepts to provide a visually attractive and
easy to use experience.
gnome-shell is a required component of the GNOME desktop, i.e. it is listed in
the RequiredComponents field of /usr/share/gnome-session/sessions/gnome.session.
It is started in the window manager phase of the session.
OPTIONS
-------
*-r*, *--replace*::
Replace the running window manager
*--sm-disable*::
Disable connection to the session manager
*--sm-client-id*='ID'::
Specify session management 'ID'
*--sm-save-file*='FILE'::
Initialize session from 'FILE'
*--screen*='SCREEN'::
X screen to use
*-d*, *--display*='DISPLAY'::
X display to use
*--sync*::
Make X calls synchronous
*--version*::
Print version and exit
*--help*::
Display help and exit
*--mode*='MODE'::
Use a specific mode, e.g. "gdm" for login screen
*--list-modes*::
List possible modes and exit
*--clutter-display*='DISPLAY'::
Clutter the option display (otherwise ignored)
FILES
-----
/usr/share/gnome-session/sessions/gnome.session,
/usr/share/applications/org.gnome.Shell.desktop.
BUGS
----
The bug tracker can be reached by visiting the website
https://bugzilla.gnome.org/buglist.cgi?product=gnome-shell.
Before sending a bug report, please verify that you have the latest version
of gnome-shell. Many bugs (major and minor) are fixed at each release, and
if yours is out of date, the problem may already have been solved.
ADDITIONAL INFORMATION
----------------------
For further information, visit the website https://wiki.gnome.org/Projects/GnomeShell.

165
man/gnome-shell.xml
View File

@ -1,165 +0,0 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="gnome-shell">
<refentryinfo>
<title>gnome-shell</title>
<productname>gnome-shell</productname>
<authorgroup>
<author>
<contrib>wrote the original gnome-shell man page</contrib>
<firstname>Marcelo Jorge</firstname>
<surname>Vieira</surname>
<email>metal@alucinados.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gnome-shell</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>gnome-shell</refname>
<refpurpose>Graphical shell for the GNOME desktop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gnome-shell <arg choice="opt" rep="repeat">OPTION</arg></command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>GNOME shell provides core user
interface functions for the GNOME 3 desktop, like switching
to windows and launching applications. GNOME shell takes
advantage of the capabilities of modern graphics hardware
and introduces innovative user interface concepts to provide
a visually attractive and easy to use experience.</para>
<para>gnome-shell is a required component of
the GNOME desktop, i.e. it is listed in the
RequiredComponents field of
<filename>/usr/share/gnome-session/sessions/gnome.session</filename>.
It is started in the window manager phase of the session.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-r</option>, <option>--replace</option></term>
<listitem><para>Replace the running window manager</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sm-disable</option></term>
<listitem><para>Disable connection to the session manager</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sm-client-id=<replaceable>ID</replaceable></option></term>
<listitem><para>Specify session management <replaceable>ID</replaceable></para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sm-save-file=<replaceable>FILE</replaceable></option></term>
<listitem><para>Initialize session from <replaceable>FILE</replaceable></para></listitem>
</varlistentry>
<varlistentry>
<term><option>--screen=<replaceable>SCREEN</replaceable></option></term>
<listitem><para>X screen to use</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--display=<replaceable>DISPLAY</replaceable></option></term>
<listitem><para>X Display to use</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sync</option></term>
<listitem><para>Make X calls synchronous</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>Print version and exit</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--help</option></term>
<listitem><para>Display help and exit</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--mode=<replaceable>MODE</replaceable></option></term>
<listitem><para>Use a specific mode, e.g. "gdm" for login screen</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-modes</option></term>
<listitem><para>List possible modes and exit</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--clutter-display=<replaceable>DISPLAY</replaceable></option></term>
<listitem><para>Clutter the option display (otherwise ignored)</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Files</title>
<para>
<filename>/usr/share/gnome-session/sessions/gnome.session</filename>,
<filename>/usr/share/applications/org.gnome.Shell.desktop</filename>.</para>
</refsect1>
<refsect1>
<title>Bugs</title>
<para>The bug tracker can be reached by visiting the
website <ulink url="https://bugzilla.gnome.org/buglist.cgi?product=gnome-shell">https://bugzilla.gnome.org/buglist.cgi?product=gnome-shell</ulink>.
Before sending a bug report, please verify that you have
the latest version of gnome-shell. Many bugs (major and
minor) are fixed at each release, and if yours is out of
date, the problem may already have been solved.</para>
</refsect1>
<refsect1>
<title>Additional Information</title>
<para>For further information, visit the website
<ulink url="https://wiki.gnome.org/Projects/GnomeShell">https://wiki.gnome.org/Projects/GnomeShell</ulink>.</para>
</refsect1>
</refentry>

16
man/meson.build
View File

@ -1,19 +1,7 @@
custom_target('man page',
input: 'gnome-shell.xml',
input: ['gnome-shell.txt', 'stylesheet.xsl'],
output: 'gnome-shell.1',
command: [
xsltproc,
'-o', '@OUTPUT@',
'--nonet',
'--stringparam', 'man.output.quietly', '1',
'--stringparam', 'funcsynopsis.style', 'ansi',
'--stringparam', 'man.th.extra1.suppress', '1',
'--stringparam', 'man.authors.section.enabled', '0',
'--stringparam', 'man.copyright.section.enabled', '0',
'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
'@INPUT@'
],
build_by_default: true,
command: [a2x, '-D', '@OUTDIR@', '--xsl-file', '@INPUT1@', '-f' ,'manpage', '@INPUT0@'],
install_dir: mandir + '/man1',
install: true
)

27
man/stylesheet.xsl Normal file
View File

@ -0,0 +1,27 @@
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>
<xsl:template match="variablelist/title">
<xsl:text>.PP&#10;</xsl:text>
<xsl:call-template name="bold">
<xsl:with-param name="node" select="."/>
<xsl:with-param name="context" select=".."/>
</xsl:call-template>
<xsl:text>&#10;</xsl:text>
</xsl:template>
<xsl:template match="varlistentry[preceding-sibling::title]">
<xsl:if test="not(preceding-sibling::varlistentry)">
<xsl:text>.RS 4&#10;</xsl:text>
<!-- comment out the leading .PP added by the original template -->
<xsl:text>.\"</xsl:text>
</xsl:if>
<xsl:apply-imports/>
<xsl:if test="position() = last()">
<xsl:text>.RE&#10;</xsl:text>
</xsl:if>
</xsl:template>
</xsl:stylesheet>

3
meson.build
View File

@ -126,8 +126,7 @@ else
endif
if get_option('man')
xsltproc = find_program('xsltproc')
a2x = find_program('a2x')
subdir('man')
endif