mirror/flatpak
1
0
Fork 0
mirror of https://github.com/flatpak/flatpak.git synced 2026-03-16 06:02:13 -04:00
Code Issues Packages Projects Releases Wiki Activity

Some larger documentation rework

Browse Source 
Move repetitive parts to the main man page, group command list
with sections, improve consistency of the command man pages,
add cross-references.
This commit is contained in:
Matthias Clasen
2015-01-16 23:55:35 -05:00
parent 7481a2a2f5
commit cf723600a8
15 changed files with 230 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
doc/xdg-app-add-repo.xml
View File

@@ -41,18 +41,9 @@
<title>Description</title>
<para>
Adds a remote repository configuration. <arg choice="plain">NAME</arg>
is the name for the new remote, and <arg choice="plain">URL</arg> is
the location for the repository.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
repository is located in <filename>$prefix/share/xdg-app/repo</filename>,
and the per-user repository is in <filename>$HOME/.local/share/xdg-app/repo</filename>.
</para>
<para>
xdg-app uses OSTree, and the repositories it uses are OSTree repositories
that can be manipulated with the <command>ostree</command> utility.
Adds a remote repository to the xdg-app repository configuration.
<arg choice="plain">NAME</arg> is the name for the new remote, and
<arg choice="plain">URL</arg> is the location for the repository.
</para>
</refsect1>
@@ -128,9 +119,9 @@
<title>See also</title>
<para>
<citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-delete-repo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-delete-repo</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-list-repos</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>

22
doc/xdg-app-build-export.xml
View File

@@ -52,8 +52,9 @@
</para>
<para>
If <arg choice="plain">LOCATION</arg> exists, it is assumed to
be an OSTree repository, otherwise a new repository is created
at this location.
be an OSTree repository, otherwise a new OSTree repository is
created at this location. The repository can be inspected with
the <command>ostree</command> tool.
</para>
<para>
The contents of <arg choice="plain">DIRECTORY</arg> are committed
@@ -66,8 +67,8 @@
</para>
<para>
After this command, <arg choice="plain">LOCATION</arg> can be
used as the repository location for xdg-app add-repo,
either by exporting it over http, or directly as a file: url.
used as the repository location for xdg-app add-repo, either by
exporting it over http, or directly with a file: url.
</para>
</refsect1>
@@ -122,4 +123,17 @@ Content Bytes Written: 305
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-init</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-finish</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

17
doc/xdg-app-build-finish.xml
View File

@@ -40,7 +40,7 @@
<title>Description</title>
<para>
Finalizes a build directory, to prepare it for bundling.
Finalizes a build directory, to prepare it for exporting.
<arg choice="plain">DIRECTORY</arg> is the name of the directory.
</para>
<para>
@@ -92,7 +92,8 @@
<listitem><para>
Set the KEY in the [Environment] group to true. KEY must
be one of: x11, ipc, pulseaudio, system-dbus, session-dbus,
network, host-fs, homedir.
network, host-fs, homedir. This option can be used multiple
times.
</para></listitem>
</varlistentry>
@@ -131,4 +132,16 @@ Please review the exported files and the metadata
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-init</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

14
doc/xdg-app-build-init.xml
View File

@@ -51,7 +51,7 @@
</para>
<para>
The result of this command is that a <filename>metadata</filename>
is created inside the given directory. Additionally, empty
file is created inside the given directory. Additionally, empty
<filename>files</filename> and <filename>var</filename> subdirectories
are created.
</para>
@@ -129,4 +129,16 @@
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-finish</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

16
doc/xdg-app-build.xml
View File

@@ -45,8 +45,8 @@
must have been initialized with <command>xdg-app build-init</command>.
</para>
<para>
The sdk that is specfied in the <filename>metadata</filename> for the
directory is mounted at <filename>/usr</filename> and the
The sdk that is specfied in the <filename>metadata</filename> file
in the directory is mounted at <filename>/usr</filename> and the
<filename>files</filename> and <filename>var</filename> subdirectories
are mounted at <filename>/self</filename> and <filename>/var</filename>,
respectively. They are writable, and their contents are preserved between
@@ -81,4 +81,16 @@
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-init</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-finish</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-build-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

17
doc/xdg-app-delete-repo.xml
View File

@@ -40,18 +40,9 @@
<title>Description</title>
<para>
Removes a remote repository configuration.
Removes a remote repository from the xdg-app repository configuration.
<arg choice="plain">NAME</arg> is the name of an existing remote.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
repository is located in <filename>$prefix/share/xdg-app/repo</filename>,
and the per-user repository is in <filename>$HOME/.local/share/xdg-app/repo</filename>.
</para>
<para>
xdg-app uses OSTree, and the repositories it uses are OSTree repositories
that can be manipulated with the <command>ostree</command> utility.
</para>
</refsect1>
@@ -110,9 +101,9 @@
<title>See also</title>
<para>
<citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-add-repo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-add-repo</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-list-repos</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>

26
doc/xdg-app-install-app.xml
View File

@@ -45,17 +45,10 @@
Installs an application. <arg choice="plain">REPOSITORY</arg> must
name an existing remote. <arg choice="plain">APP</arg> is the
name of the application to install. Optionally,
<arg choice="opt">BRANCH</arg> can be specified to install a specific
branch. Note that xdg-app allows to have multiple branches of an
application installed at the same time.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
applications are located in <filename>$prefix/share/xdg-app/app</filename>,
and the per-user runtimes are in <filename>$HOME/.local/share/xdg-app/app</filename>.
</para>
<para>
xdg-app uses OSTree, and installed applications are OSTree checkouts.
<arg choice="plain">BRANCH</arg> can be specified to install a branch
other than the default "master" branch. Note that xdg-app allows to
have multiple branches of an application installed and used at the
same time.
</para>
</refsect1>
@@ -120,4 +113,15 @@
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-update-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-list-apps</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

28
doc/xdg-app-install-runtime.xml
View File

@@ -45,17 +45,9 @@
Installs a runtime. <arg choice="plain">REPOSITORY</arg> must
name an existing remote. <arg choice="plain">RUNTIME</arg> is the
name of the runtime to install. Optionally,
<arg choice="opt">BRANCH</arg> can be specified to install a specific
branch. Note that xdg-app allows having multiple branches of a runtime
installed and used at the same time.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
runtimes are located in <filename>$prefix/share/xdg-app/runtime</filename>,
and the per-user runtimes are in <filename>$HOME/.local/share/xdg-app/runtinme</filename>.
</para>
<para>
xdg-app uses OSTree, and installed runtimes are OSTree checkouts.
<arg choice="plain">BRANCH</arg> can be specified to install a branch
other than the default "master" branch. Note that xdg-app allows having
multiple branches of a runtime installed and used at the same time.
</para>
</refsect1>
@@ -88,7 +80,8 @@
<term><option>--arch=ARCH</option></term>
<listitem><para>
The architecture to install for.
The architecture to install, instead of the architecture
of the host system.
</para></listitem>
</varlistentry>
@@ -120,4 +113,15 @@
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-update-runtime</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-list-runtimes</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

21
doc/xdg-app-list-apps.xml
View File

@@ -39,15 +39,7 @@
<title>Description</title>
<para>
Lists installed applications.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
applications are located in <filename>$prefix/share/xdg-app/app</filename>,
and the per-user runtimes are in <filename>$HOME/.local/share/xdg-app/app</filename>.
</para>
<para>
xdg-app uses OSTree, and installed appications are OSTree checkouts.
Lists the names of the installed applications.
</para>
</refsect1>
@@ -118,4 +110,15 @@ org.gnome.GEdit
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-install-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-update-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

15
doc/xdg-app-list-repos.xml
View File

@@ -41,15 +41,6 @@
<para>
Lists the known remote repositories.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
repository is located in <filename>$prefix/share/xdg-app/repo</filename>,
and the per-user repository is in <filename>$HOME/.local/share/xdg-app/repo</filename>.
</para>
<para>
xdg-app uses OSTree, and the repositories it uses are OSTree repositories
that can be manipulated with the <command>ostree</command> utility.
</para>
</refsect1>
@@ -119,9 +110,9 @@ testrepo http://209.132.179.91/repo/
<title>See also</title>
<para>
<citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-add-repo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-add-repo</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-delete-repo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>

22
doc/xdg-app-list-runtimes.xml
View File

@@ -39,15 +39,7 @@
<title>Description</title>
<para>
Lists installed runtimes.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
runtimes are located in <filename>$prefix/share/xdg-app/runtime</filename>,
and the per-user runtimes are in <filename>$HOME/.local/share/xdg-app/runtinme</filename>.
</para>
<para>
xdg-app uses OSTree, and installed runtimes are OSTree checkouts.
Lists the names of the installed runtimes.
</para>
</refsect1>
@@ -120,4 +112,16 @@ org.gnome.Platform/x86_64/3.14
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-install-runtime</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-update-runtime</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

14
doc/xdg-app-run.xml
View File

@@ -41,8 +41,9 @@
<title>Description</title>
<para>
Runs an application in a sandboxed environment. <arg choice="plain">APP</arg> must
name an installed application.
Runs an application in a sandboxed environment.
<arg choice="plain">APP</arg> must name an installed application.
Extra arguments are passed on to the application.
</para>
<para>
xdg-app creates a sandboxed environment for the application to run in
@@ -132,4 +133,13 @@
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

22
doc/xdg-app-update-app.xml
View File

@@ -43,8 +43,15 @@
<para>
Updates an application. <arg choice="plain">APP</arg> is the
name of an installed application. Optionally,
<arg choice="opt">BRANCH</arg> can be specified to update a
specific branch.
<arg choice="plain">BRANCH</arg> can be specified to update a
branch other than the default "master" branch.
</para>
<para>
Note that updating a runtime is different from installing
a newer branch, and application updates are expected to keep
strict compatibility. If an application update does cause
a problem, it is possible to go back to the previous
version, with the --commit option.
</para>
</refsect1>
@@ -109,4 +116,15 @@
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-install-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-list-apps</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

22
doc/xdg-app-update-runtime.xml
View File

@@ -43,15 +43,17 @@
<para>
Updates a runtime. <arg choice="plain">RUNTIME</arg> is the
name of an installed runtime. Optionally,
<arg choice="opt">BRANCH</arg> can be specified to update a
specific branch.
<arg choice="plain">BRANCH</arg> can be specified to update a
branch other than the default "master" branch.
</para>
<para>
Note that updating a runtime is different from installing
a newer branch, and runtime updates are expected to keep
strict compatibility, so that applications can be guaranteed
to keep running against an updated version of the runtime
they were built against.
they were built against. If a runtime update does cause
a problem, it is possible to go back to the previous
version, with the --commit option.
</para>
</refsect1>
@@ -84,7 +86,8 @@
<term><option>--arch=ARCH</option></term>
<listitem><para>
The architecture to update for.
The architecture to update, instead of the architecture
of the host system.
</para></listitem>
</varlistentry>
@@ -116,4 +119,15 @@
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-install-runtime</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>xdg-app-list-runtimes</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

54
doc/xdg-app.xml
View File

@@ -41,11 +41,29 @@
<para>
xdg-app is a tool for managing applications and the runtimes
the use. In the xdg-app model, applications can be built and
distributed independently from the host system the are used
they use. In the xdg-app model, applications can be built and
distributed independently from the host system they are used
on, and they are isolated from the host system ('sandboxed')
to some degree, at runtime.
</para>
<para>
xdg-app can operate in system-wide or per-user mode. The system-wide
data (runtimes, applications and configuration) is located in
<filename>$prefix/share/xdg-app/</filename>, and the per-user
data is in <filename>$HOME/.local/share/xdg-app/</filename>.
Below these locations, there is a local repository in the
<filename>repo/</filename> subdirectory and installed runtimes
and applications are in the corresponding <filename>runtime/</filename>
and <filename>app/</filename> subdirectories.
</para>
<para>
xdg-app uses OSTree to distribute and deploy data. The repositories
it uses are OSTree repositories and can be manipulated with the
<command>ostree</command> utility. Installed runtimes and
applications are OSTree checkouts.
</para>
</refsect1>
<refsect1>
@@ -85,7 +103,7 @@
<refsect1>
<title>Commands</title>
<para>The following commands are available:</para>
<para>Commands related to repository configuration:</para>
<variablelist>
<varlistentry>
@@ -116,6 +134,11 @@
Show available runtimes and applications.
</para></listitem>
</varlistentry>
</variablelist>
<para>Commands for handling installed runtimes:</para>
<variablelist>
<varlistentry>
<term><citerefentry><refentrytitle>xdg-app-install-runtime</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
@@ -137,6 +160,11 @@
List installed runtimes.
</para></listitem>
</varlistentry>
</variablelist>
<para>Commands for handling installed applications:</para>
<variablelist>
<varlistentry>
<term><citerefentry><refentrytitle>xdg-app-install-app</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
@@ -158,6 +186,11 @@
List installed applications.
</para></listitem>
</varlistentry>
</variablelist>
<para>Commands for running applications:</para>
<variablelist>
<varlistentry>
<term><citerefentry><refentrytitle>xdg-app-run</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
@@ -165,6 +198,11 @@
Run an application.
</para></listitem>
</varlistentry>
</variablelist>
<para>Commands for building applications:</para>
<variablelist>
<varlistentry>
<term><citerefentry><refentrytitle>xdg-app-build-init</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
@@ -196,4 +234,14 @@
</variablelist>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
</para>
</refsect1>
</refentry>