From 740aa102eec65abf8dcfeeac043ecbcde74f2bf8 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 21 Oct 2013 17:53:33 -0400 Subject: [PATCH] docs: add docbook based man pages This commit adds man pages for the plymouthd and plymouth client commands. --- Makefile.am | 6 +- configure.ac | 12 ++ docs/Makefile.am | 33 +++- docs/plymouth-set-default-theme.xml | 103 +++++++++++ docs/plymouth.8 | 62 ------- docs/plymouth.xml | 86 +++++++++ docs/plymouth1.xml | 351 ++++++++++++++++++++++++++++++++++++ docs/plymouthd.xml | 121 +++++++++++++ 8 files changed, 708 insertions(+), 66 deletions(-) create mode 100644 docs/plymouth-set-default-theme.xml delete mode 100644 docs/plymouth.8 create mode 100644 docs/plymouth.xml create mode 100644 docs/plymouth1.xml create mode 100644 docs/plymouthd.xml diff --git a/Makefile.am b/Makefile.am index b322463..395c91b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,13 +1,17 @@ -SUBDIRS = src themes images scripts docs systemd-units +SUBDIRS = src themes images scripts systemd-units + +if BUILD_DOCUMENTATION +SUBDIRS += docs +endif DISTCHECK_CONFIGURE_FLAGS = --disable-tests --without-system-root-install EXTRA_DIST = ChangeLog \ README MAINTAINERCLEANFILES = aclocal.m4 \ config.h.in \ config.h.in~ \ config.sub \ configure \ Makefile.in diff --git a/configure.ac b/configure.ac index bb0207d..6b957d9 100644 --- a/configure.ac +++ b/configure.ac @@ -198,60 +198,72 @@ if test x$enable_libdrm_nouveau = xyes; then fi AC_ARG_ENABLE(libkms, AS_HELP_STRING([--enable-libkms],[enable building with libkms support]),enable_libkms=$enableval,enable_libkms=no) AM_CONDITIONAL(ENABLE_LIBKMS, [test "$enable_libkms" = yes]) if test x$enable_libkms = xyes; then PKG_CHECK_MODULES(LIBKMS, [libdrm libkms]) AC_SUBST(LIBKMS_CFLAGS) AC_SUBST(LIBKMS_LIBS) AC_DEFINE(PLY_ENABLE_LIBKMS, 1, [Enable support for libkms abstraction over drm drivers]) fi AC_ARG_ENABLE(drm, AS_HELP_STRING([--enable-drm-renderer],[enable building drm kms support]),enable_drm_renderer=$enableval,enable_drm_renderer=yes) AM_CONDITIONAL(ENABLE_DRM_RENDERER, [test "$enable_drm_renderer" = yes]) if test x$enable_drm_renderer = xyes; then PKG_CHECK_MODULES(DRM, [libdrm]) fi DRM_CFLAGS="$DRM_CFLAGS $DRM_INTEL_CFLAGS $DRM_RADEON_CFLAGS $DRM_NOUVEAU_CFLAGS $LIBKMS_CFLAG" DRM_LIBS="$DRM_LIBS $DRM_INTEL_LIBS $DRM_RADEON_LIBS $DRM_NOUVEAU_LIBS $LIBKMS_LIBS" AC_SUBST(DRM_CFLAGS) AC_SUBST(DRM_LIBS) AC_ARG_ENABLE(tracing, AS_HELP_STRING([--enable-tracing],[enable verbose tracing code]),enable_tracing=$enableval,enable_tracing=yes) if test x$enable_tracing = xyes; then AC_DEFINE(PLY_ENABLE_TRACING, 1, [Build in verbose debug tracing spew]) fi +AC_ARG_ENABLE(documentation, + AS_HELP_STRING([--enable-documentation], + [build documentation]),, + enable_documentation=yes) +if test x$enable_documentation = xyes; then + AC_PATH_PROG([XSLTPROC], [xsltproc]) + if test x$XSLTPROC = x; then + AC_MSG_ERROR([xsltproc is required to build documentation]) + fi +fi +AM_CONDITIONAL(BUILD_DOCUMENTATION, test x$enable_documentation = xyes) + AC_ARG_ENABLE(tests, AS_HELP_STRING([--enable-tests],[build tests]),enable_tests=$enableval,enable_tests=yes) AM_CONDITIONAL(ENABLE_TESTS, [test "$enable_tests" = yes]) AC_ARG_ENABLE(gdm-transition, AS_HELP_STRING([--enable-gdm-transition],[enable smooth transition to gdm]),enable_gdm_transition=$enableval,enable_gdm_transition=no) if test x$enable_gdm_transition = xyes; then AC_DEFINE(PLY_ENABLE_DEPRECATED_GDM_TRANSITION, 1, [Enable deprecated smooth transition to GDM]) fi AC_ARG_ENABLE(upstart-monitoring, AS_HELP_STRING([--enable-upstart-monitoring],[listen for messages on the Upstart D-Bus interface]),enable_upstart_monitoring=$enableval,enable_upstart_monitoring=no) if test x$enable_upstart_monitoring = xyes; then PKG_CHECK_MODULES(DBUS, [dbus-1]) AC_SUBST(DBUS_CFLAGS) AC_SUBST(DBUS_LIBS) AC_CHECK_HEADERS([ncursesw/term.h ncurses/term.h term.h], [break]) AC_CHECK_LIB([ncursesw], [initscr], [CURSES_LIBS="$CURSES_LIBS -lncursesw"], [AC_CHECK_LIB([ncurses], [initscr], [CURSES_LIBS="$CURSES_LIBS -lncurses"], [AC_CHECK_LIB([curses], [initscr], [CURSES_LIBS="$CURSES_LIBS -lcurses"], [AC_MSG_ERROR([no curses library found])])])]) AC_SUBST(CURSES_LIBS) fi AM_CONDITIONAL(ENABLE_UPSTART_MONITORING, [test "$enable_upstart_monitoring" = yes]) AC_ARG_ENABLE(systemd-integration, AS_HELP_STRING([--enable-systemd-integration],[coordinate boot up with systemd]),enable_systemd_integration=$enableval,enable_systemd_integration=no) AM_CONDITIONAL(ENABLE_SYSTEMD_INTEGRATION, [test "$enable_systemd_integration" = yes]) diff --git a/docs/Makefile.am b/docs/Makefile.am index dedda55..1a9f7ea 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,4 +1,31 @@ -dist_man_MANS = plymouth.8 +XSLTPROC_FLAGS = \ + --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 -%.html: %.txt - asciidoc $(ASCIIDOC_OPTS) -a toc $*.txt + +plymouth.1: plymouth1.xml + $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +%.8: %.xml + $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +%.1: %.xml + $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +man_MANS = \ + plymouth.1 \ + plymouth.8 \ + plymouthd.8 \ + plymouth-set-default-theme.1 + +EXTRA_DIST = \ + plymouth.xml \ + plymouth1.xml \ + plymouth-set-default-theme.xml \ + plymouthd.xml + +CLEANFILES = $(man_MANS) diff --git a/docs/plymouth-set-default-theme.xml b/docs/plymouth-set-default-theme.xml new file mode 100644 index 0000000..efb051e --- /dev/null +++ b/docs/plymouth-set-default-theme.xml @@ -0,0 +1,103 @@ + + + + + + + plymouth-set-default-theme + plymouth + + + + Developer + Kristian + Høgsberg + + + Developer + Ray + Strode + + + + + + + plymouth-set-default-theme + 1 + User Commands + + + + plymouth-set-default-theme + Set the plymouth theme + + + + + plymouth-set-default-theme OPTION THEME + + + + + Description + + +When called with a argument, +the plymouth-set-default-theme command +changes the preferred boot theme and also performs the necessary +regeneration of the initial ramdisk (initrd) since plymouth is loaded +from the boot loader from the initrd prior to the mounting of the root +filesystem. + + + +If plymouth-set-default-theme is invoked with no options +or parameters, it shows the currently selected theme by default. This output +is used by the helper scripts plymouth-generate-initrd and +plymouth-update-initrd to set the proper theme in the initial ramdisk. + + + + + + Options + + The following options are understood: + + + + , + Show summary of options. + + + + , + List available themes. + + + + , + Reset to default theme. + + + + , + Rebuild initrd (necessary after changing theme). + + + + + + See Also + + grub8, + plymouth8, + plymouthd8, + plymouth1, + http://www.freedesktop.org/wiki/Software/Plymouth + + + + diff --git a/docs/plymouth.8 b/docs/plymouth.8 deleted file mode 100644 index 7f4766b..0000000 --- a/docs/plymouth.8 +++ /dev/null @@ -1,62 +0,0 @@ -\" Hey, EMACS: -*- nroff -*- -.TH PLYMOUTH 8 "December 15, 2009" -.SH NAME -plymouth \- A graphical boot system and logger -.SH SYNOPSIS -.B plymouth-set-default-theme -.RI [ options ] " \" -.SH DESCRIPTION -\fBplymouth\fP is a graphical boot system for Linux which takes advantage of the kernel-based -mode setting (KMS) available for modern graphic cards to provide a seamless, flickerfree -and attractive boot screen. It allows to choose between various, static or -animated graphical themes to spruce up the startup and avoid the noise -generated by the vast amount of kernel messages while the machine boots into X. -On systems where kernel-based mode setting is not available, plymouth falls -back to a text mode boot screen which provides a simple progress bar to provide -feedback during boot. -.PP -To configure plymouth, that is to choose and install the preferred boot theme, the -user has to invoke \fBplymouth-set-default-theme\fP. It changes the configuration -to the new theme and also performs the necessary regeneration of the initial ramdisk -(initrd) since plymouth is loaded from the boot loader from the initrd -prior to the mounting of the root filesystem. The options available to this -script are explained in the \fBOPTIONS\fP paragraph. -.PP -In order for the configured default plymouth theme to be loaded during boot, -the option `splash' (or `rhgb' for backward compatibility with the RHGB boot -splash) must be provided at the kernel command line. With this command line -option, plymouth will default to showing detailed boot output. -.SH OPTIONS -plymouth-set-default-theme follows the usual GNU command line syntax, with long -options starting with two dashes (`-') and short variants of each of them. -.TP -.B \-h, \-\-help -Show summary of options. -.TP -.B \-l, \-\-list -List available themes. -.TP -.B \-r, \-\-reset -Reset to default theme. -.TP -.B \-R, \-\-rebuild\-initrd -Rebuild initrd (necessary after changing theme). -.TP -.B \ -Name of new theme to use. If you want to see which themes are available, invoke the script with just \-\-list. -.PP -If plymouth-set-default-theme is invoked with no options or parameters, it shows the currently selected theme -by default. This output is used by the helper scripts `plymouth-generate-initrd' and `plymouth-update-initrd' -to set the proper theme in the initial ramdisk. -.SH SEE ALSO -.BR grub (8) -.br -.SH AUTHOR -plymouth was originally prototyped and named by Kristian Høgsberg , -originally written by Ray Strode and has had significant contributions -from Charlie Brej . It has also had contributions from -Peter Jones , Adam Jackson , -Frederic Crozat and others. -It can be downloaded here: . -.PP -This manual page was written by Adrian Glaubitz . diff --git a/docs/plymouth.xml b/docs/plymouth.xml new file mode 100644 index 0000000..0f196c6 --- /dev/null +++ b/docs/plymouth.xml @@ -0,0 +1,86 @@ + + + + + + + plymouth + plymouth + + + + Developer + Kristian + Høgsberg + + + Developer + Ray + Strode + + + + + + + plymouth + 8 + System Administration + + + + plymouth + A graphical boot system and logger + + + + Description + + +plymouth is a graphical boot system for Linux which takes advantage of +the kernel-based mode setting (KMS) available for modern graphic cards +to provide a seamless, flickerfree and attractive boot screen. It +allows to choose between various, static or animated graphical themes +to spruce up the startup and avoid the noise generated by the vast +amount of kernel messages while the machine boots into X. On systems +where kernel-based mode setting is not available, plymouth falls back +to a text mode boot screen which provides a simple progress bar to pro‐ +vide feedback during boot. + + +In order for the configured default plymouth theme to be loaded during +boot, the option `splash' (or `rhgb' for backward compatibility with +the RHGB boot splash) must be provided at the kernel command line. +Without this command line option, plymouth will default to showing +detailed boot output. + + + +During the boot process, the user can switch between the graphical theme +and the detailed boot output using the Escape key. + + + + + + See Also + + grub8, + plymouth-set-theme1, + plymouthd8, + plymouth1, + http://www.freedesktop.org/wiki/Software/Plymouth + + + + + Authors + +plymouth was originally prototyped and named by Kristian Høgsberg, +originally written by Ray Strode and has had significant contributions from +Charlie Brej. It has also had contributions from Peter Jones, Adam Jackson, +Frederic Crozat and others. + + + diff --git a/docs/plymouth1.xml b/docs/plymouth1.xml new file mode 100644 index 0000000..b484599 --- /dev/null +++ b/docs/plymouth1.xml @@ -0,0 +1,351 @@ + + + + + + + plymouth + plymouth + + + + Developer + Kristian + Høgsberg + + + Developer + Ray + Strode + + + + + + + plymouth + 1 + User Commands + + + + plymouth + Send commands to plymouthd + + + + + plymouth OPTION + + + plymouth COMMAND OPTION + + + + + Description + + +The plymouth sends commands to a running +plymouthd. This is used during the boot +process to control the display of the graphical boot splash. + + + + + + Options + + +The following options are understood. These options are supported +for compatibility with the old rhgb-client interface, +and have been replaced by the commands that are described in the +next section. + + + + + + Show summary of options. + + + + + Enable verbose debug logging. + + + + + Get directory where splash plugins are installed. + + + + + Tell plymouthd that the new root filesystem is mounted. + + + + + Tell plymouthd to quit. + + + + + Check if plymouthd is running. + + + + + Check if plymouthd has an active vt. + + + + + Tell plymouthd root filesystem is mounted read-write. + + + + + Show the splash screen. + + + + + Hide the splash screen. + + + + + Ask the user for a password. + + + + + Remove sensitivity to a keystroke. + + + + + Tell plymouthd an update about boot progress. + + + + + Tell plymouthd there were errors during boot. + + + + + Wait for plymouthd to quit. + + + + + + Commands + + +The following commands are understood: + + + + change-mode OPTION + Change the operation mode. + + + + Start the system up + + + + Shutting the system up + + + + Applying updates + + + + + + system-update OPTION + Tell plymouthd about boot progress. + + + + The percentage progress of the updates + + + + + + update OPTION + Tell plymouthd about boot status changes. + + + + Tell plymouthd the current boot status + + + + + + update-root-fs OPTION + Tell plymouthd about root filesystem changes. + + + + Root filesystem is about to change + + + + Root filesystem is no longer read-only + + + + + + show-splash + Tell plymouthd to show splash screen. + + + hide-splash + Tell plymouthd to hide splash screen. + + + ask-for-password OPTION + Ask the user for a password. + + + + Command to send password to via standard input + + + + Message to display when asking for password + + + + Number of times to ask before giving up (requires ) + + + + Don't pause boot progress bar while asking + + + + + + ask-question + Ask the user a question. + + + + Command to send the answer to via standard input + + + + Message to display when asking the question + + + + Don't pause boot progress bar while asking + + + + + + display-message OPTION + Display a message. + + + + The message text + + + + + + hide-message OPTION + Hide a message. + + + + The message text + + + + + + watch-keystroke OPTION + Become sensitive to a keystroke. + + + + Command to send keystroke to via standard input + + + + Keys to become sensitive to + + + + + + ignore-keystroke OPTION + Remove sensitivity to a keystroke. + + + + Keys to remove sensitivitiy from + + + + + + pause-progress + Pause boot progress bar. + + + unpause-progress + Unpause boot progress bar. + + + report-error + Tell plymouthd there were errors during boot. + + + deactivate + Tell plymouthd to deactivate. + + + reactivate + Tell plymouthd to reactivate. + + + quit OPTION + Tell plymouthd to quit. + + + + Don't explicitly hide boot splash on exit + + + + + + + + + + See Also + + grub8, + plymouth8, + plymouthd8, + http://www.freedesktop.org/wiki/Software/Plymouth + + + + diff --git a/docs/plymouthd.xml b/docs/plymouthd.xml new file mode 100644 index 0000000..4e7e499 --- /dev/null +++ b/docs/plymouthd.xml @@ -0,0 +1,121 @@ + + + + + + + plymouthd + plymouth + + + + Developer + Kristian + Høgsberg + + + Developer + Ray + Strode + + + + + + + plymouthd + 8 + System Administration + + + + plymouthd + The plymouth daemon + + + + + plymouthd OPTION + + + + + Description + + +The plymouthd daemon is usually run out of +the initrd. It does the heavy lifting of the plymouth system, logging +the session and showing the splash screen. + + +The plymouth is used to send commands to plymouthd +that control its behaviour. + + + + + + Options + + The following options are understood: + + + + + Show summary of options. + + + + + Redirect console messages from screen to log. + + + + + Do not daemonize. + + + + + Output debugging information. + + + + + File to write debugging information to. + + + + + Set mode to either boot or shutdown. + + + + + Write the PID of the daemon to a file. + + + + + Fake kernel commandline to use. + + + + + TTY to ues instead of default. + + + + + + See Also + + grub8, + plymouth8, + plymouth1, + http://www.freedesktop.org/wiki/Software/Plymouth + + + + -- 1.8.3.1