[Draft] Test commit to preview the man page

doc/man/markdown/cockpit-desktop-a.1

@@ -0,0 +1,77 @@
+'\" t
+.\"     Title: cockpit-desktop
+.\"    Author: [see the "AUTHOR(S)" section]
+.\" Generator: Asciidoctor 2.0.20
+.\"      Date: 2024-10-28
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "COCKPIT\-DESKTOP" "1" "2024-10-28" "\ \&" "\ \&"
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.ss \n[.ss] 0
+.nh
+.ad l
+.de URL
+\fI\\$2\fP <\\$1>\\$3
+..
+.als MTO URL
+.if \n[.g] \{\
+.  mso www.tmac
+.  am URL
+.    ad l
+.  .
+.  am MTO
+.    ad l
+.  .
+.  LINKSTYLE blue R < >
+.\}
+.SH "NAME"
+cockpit-desktop \- Cockpit Desktop integration
+.SH "SYNOPSIS"
+.sp
+\fBcockpit\-desktop\fP {URLPATH} [SSH_HOST]
+.SH "DESCRIPTION"
+.sp
+The \f(CRcockpit\-desktop\fP program provides secure access to Cockpit pages in
+an already running desktop session. It starts a web server
+(\f(CRcockpit\-ws\fP) and a web browser in an isolated network namespace, and a
+\f(CRcockpit\-bridge(8)\fP in the running user session.
+.sp
+This avoids having to log into Cockpit, and having to enable
+\f(CRcockpit.socket\fP system\-wide. The network isolation ensures that no
+other user, and not even other processes in the user\(cqs session, can
+access this local web server.
+.sp
+\f(CRURLPATH\fP is the Cockpit page to open, i. e. the path component of
+Cockpit URLs. It is highly recommended to only open a
+.URL "https://cockpit\-project.org/guide/latest/embedding.html" "particular page frame" ","
+not the entire Cockpit navigation and menu. For example, the
+path \f(CR/cockpit/@localhost/storage/index.html\fP will open the Storage
+page. It is also possible to give abbreviated forms of urls, such as
+\(lqstorage\(rq or \(lqnetwork/firewall\(rq.
+.sp
+\f(CRSSH_HOST\fP is an optional SSH remote host specification (\f(CRhostname\fP or
+\f(CRusername@hostname\fP). If given, \f(CRcockpit\-bridge\fP will be started on the
+remote host through \f(CRssh(1)\fP instead, i. e. the Cockpit web browser will
+show that remote host. Note that this is more of an experimental/demo
+feature.
+.SH "ENVIRONMENT"
+.sp
+The \f(CRBROWSER\fP environment variable specifies the browser command (and
+possibly options) that will be used to open the requested Cockpit page.
+If not set, \f(CRcockpit\-desktop\fP attempts to use an internal minimalistic
+WebKit browser, and failing that, will attempt to detect some reasonable
+alternatives.
+.SH "BUGS"
+.sp
+Please send bug reports to either the distribution bug tracker or the
+.URL "https://github.com/cockpit\-project/cockpit/issues/new" "upstream bug tracker" "."
+.SH "AUTHOR"
+.sp
+Cockpit has been written by many
+.URL "https://github.com/cockpit\-project/cockpit/" "contributors" "."
+.SH "SEE ALSO"
+.sp
+\f(CRcockpit\-ws(8)\fP, \f(CRcockpit\-bridge(1)\fP

doc/man/markdown/cockpit-desktop.1

@@ -0,0 +1,79 @@
+.\" Automatically generated by Pandoc 3.1.3
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.TH "cockpit-desktop" "1" "" "" "Cockpit Desktop integration"
+.hy
+.SH NAME
+.PP
+cockpit-desktop - Cockpit Desktop integration
+.SH SYNOPSIS
+.PP
+\ \ \ \f[B]cockpit-desktop\f[R] {URLPATH} [SSH_HOST]
+.SH DESCRIPTION
+.PP
+The \f[V]cockpit-desktop\f[R] program provides secure access to Cockpit
+pages in an already running desktop session.
+It starts a web server (\f[V]cockpit-ws\f[R]) and a web browser in an
+isolated network namespace, and a \f[V]cockpit-bridge(8)\f[R] in the
+running user session.
+.PP
+This avoids having to log into Cockpit, and having to enable
+\f[V]cockpit.socket\f[R] system-wide.
+The network isolation ensures that no other user, and not even other
+processes in the user\[aq]s session, can access this local web server.
+.PP
+\f[V]URLPATH\f[R] is the Cockpit page to open, i.
+e.
+the path component of Cockpit URLs.
+It is highly recommended to only open a particular page
+frame (https://cockpit-project.org/guide/latest/embedding.html), not the
+entire Cockpit navigation and menu.
+For example, the path
+\f[V]/cockpit/\[at]localhost/storage/index.html\f[R] will open the
+Storage page.
+It is also possible to give abbreviated forms of urls, such as
+\[dq]\f[V]storage\f[R]\[dq] or \[dq]\f[V]network/firewall\f[R]\[dq].
+.PP
+\f[V]SSH_HOST\f[R] is an optional SSH remote host specification
+(\f[V]hostname\f[R] or \f[V]username\[at]hostname\f[R]).
+If given, \f[V]cockpit-bridge\f[R] will be started on the remote host
+through \f[V]ssh(1)\f[R] instead, i.
+e.
+the Cockpit web browser will show that remote host.
+Note that this is more of an experimental/demo feature.
+.SH ENVIRONMENT
+.PP
+The \f[V]BROWSER\f[R] environment variable specifies the browser command
+(and possibly options) that will be used to open the requested Cockpit
+page.
+If not set, \f[V]cockpit-desktop\f[R] attempts to use an internal
+minimalistic WebKit browser, and failing that, will attempt to detect
+some reasonable alternatives.
+.SH BUGS
+.PP
+Please send bug reports to either the distribution bug tracker or the
+upstream bug
+tracker (https://github.com/cockpit-project/cockpit/issues/new).
+.SH AUTHOR
+.PP
+Cockpit has been written by many
+contributors (https://github.com/cockpit-project/cockpit/).
+.SH SEE ALSO
+.SH NOTES
+.PP
+(Possible rendering of footnotes instead of inline links)
+.PP
+\f[B]cockpit-ws\f[R](8), \f[B]cockpit-bridge\f[R](1)

doc/man/markdown/cockpit-desktop.1.md

@@ -0,0 +1,59 @@
+% cockpit-desktop(1) | Cockpit Desktop integration
+
+# NAME
+
+cockpit-desktop - Cockpit Desktop integration
+
+# SYNOPSIS
+
+|    `**cockpit-desktop** {URLPATH} [SSH_HOST]`
+
+
+# DESCRIPTION
+
+The `cockpit-desktop` program provides secure access to Cockpit pages in
+an already running desktop session. It starts a web server
+(`cockpit-ws`) and a web browser in an isolated network namespace, and a
+`cockpit-bridge(8)` in the running user session.
+
+This avoids having to log into Cockpit, and having to enable
+`cockpit.socket` system-wide. The network isolation ensures that no
+other user, and not even other processes in the user's session, can
+access this local web server.
+
+`URLPATH` is the Cockpit page to open, i. e. the path component of
+Cockpit URLs. It is highly recommended to only open a [particular page
+frame](https://cockpit-project.org/guide/latest/embedding.html), not the
+entire Cockpit navigation and menu. For example, the path
+`/cockpit/@localhost/storage/index.html` will open the Storage page. It
+is also possible to give abbreviated forms of urls, such as "`storage`"
+or "`network/firewall`".
+
+`SSH_HOST` is an optional SSH remote host specification (`hostname` or
+`username@hostname`). If given, `cockpit-bridge` will be started on the
+remote host through `ssh(1)` instead, i. e. the Cockpit web browser will
+show that remote host. Note that this is more of an experimental/demo
+feature.
+
+# ENVIRONMENT
+
+The `BROWSER` environment variable specifies the browser command (and
+possibly options) that will be used to open the requested Cockpit page.
+If not set, `cockpit-desktop` attempts to use an internal minimalistic
+WebKit browser, and failing that, will attempt to detect some reasonable
+alternatives.
+
+# BUGS
+
+Please send bug reports to either the distribution bug tracker or the
+[upstream bug
+tracker](https://github.com/cockpit-project/cockpit/issues/new).
+
+# AUTHOR
+
+Cockpit has been written by many
+[contributors](https://github.com/cockpit-project/cockpit/).
+
+# SEE ALSO
+
+`cockpit-ws(8)`, `cockpit-bridge(1)`

doc/man/markdown/cockpit-desktop.adoc

@@ -0,0 +1,59 @@
+= cockpit-desktop(1)
+:doctype: manpage
+
+
+== NAME
+
+cockpit-desktop - Cockpit Desktop integration
+
+== SYNOPSIS
+
+*cockpit-desktop* {URLPATH} [SSH_HOST]
+
+== DESCRIPTION
+
+The `cockpit-desktop` program provides secure access to Cockpit pages in
+an already running desktop session. It starts a web server
+(`cockpit-ws`) and a web browser in an isolated network namespace, and a
+`cockpit-bridge(8)` in the running user session.
+
+This avoids having to log into Cockpit, and having to enable
+`cockpit.socket` system-wide. The network isolation ensures that no
+other user, and not even other processes in the user's session, can
+access this local web server.
+
+`URLPATH` is the Cockpit page to open, i. e. the path component of
+Cockpit URLs. It is highly recommended to only open a
+https://cockpit-project.org/guide/latest/embedding.html[particular page frame],
+not the entire Cockpit navigation and menu. For example, the
+path `/cockpit/@localhost/storage/index.html` will open the Storage
+page. It is also possible to give abbreviated forms of urls, such as
+"`storage`" or "`network/firewall`".
+
+`SSH_HOST` is an optional SSH remote host specification (`hostname` or
+`username@hostname`). If given, `cockpit-bridge` will be started on the
+remote host through `ssh(1)` instead, i. e. the Cockpit web browser will
+show that remote host. Note that this is more of an experimental/demo
+feature.
+
+== ENVIRONMENT
+
+The `BROWSER` environment variable specifies the browser command (and
+possibly options) that will be used to open the requested Cockpit page.
+If not set, `cockpit-desktop` attempts to use an internal minimalistic
+WebKit browser, and failing that, will attempt to detect some reasonable
+alternatives.
+
+== BUGS
+
+Please send bug reports to either the distribution bug tracker or the
+https://github.com/cockpit-project/cockpit/issues/new[upstream bug tracker].
+
+== AUTHOR
+
+Cockpit has been written by many
+https://github.com/cockpit-project/cockpit/[contributors].
+
+== SEE ALSO
+
+`cockpit-ws(8)`, `cockpit-bridge(1)`

doc/man/markdown/cockpit-desktop.md

@@ -0,0 +1,64 @@
+% cockpit-desktop(1) | Cockpit Desktop integration
+
+# NAME
+
+cockpit-desktop - Cockpit Desktop integration
+
+# SYNOPSIS
+
+|    **cockpit-desktop** {URLPATH} [SSH_HOST]
+
+# DESCRIPTION
+
+The `cockpit-desktop` program provides secure access to Cockpit pages in
+an already running desktop session. It starts a web server
+(`cockpit-ws`) and a web browser in an isolated network namespace, and a
+`cockpit-bridge(8)` in the running user session.
+
+This avoids having to log into Cockpit, and having to enable
+`cockpit.socket` system-wide. The network isolation ensures that no
+other user, and not even other processes in the user\'s session, can
+access this local web server.
+
+`URLPATH` is the Cockpit page to open, i. e. the path component of
+Cockpit URLs. It is highly recommended to only open a
+[particular page frame][1], not the
+entire Cockpit navigation and menu. For example, the path
+`/cockpit/@localhost/storage/index.html` will open the Storage page. It
+is also possible to give abbreviated forms of urls, such as
+\"`storage`\" or \"`network/firewall`\".
+
+`SSH_HOST` is an optional SSH remote host specification (`hostname` or
+`username@hostname`). If given, `cockpit-bridge` will be started on the
+remote host through `ssh(1)`{.citerefentry} instead, i. e. the Cockpit
+web browser will show that remote host. Note that this is more of an
+experimental/demo feature.
+
+# ENVIRONMENT
+
+The `BROWSER` environment variable specifies the browser command (and
+possibly options) that will be used to open the requested Cockpit page.
+If not set, `cockpit-desktop` attempts to use an internal minimalistic
+WebKit browser, and failing that, will attempt to detect some reasonable
+alternatives.
+
+# BUGS
+
+Please send bug reports to either the distribution bug tracker or the
+[upstream bug
+tracker](https://github.com/cockpit-project/cockpit/issues/new).
+
+# AUTHOR
+
+Cockpit has been written by many
+[contributors](https://github.com/cockpit-project/cockpit/).
+
+# SEE ALSO
+
+# NOTES
+
+(Possible rendering of footnotes instead of inline links)
+
+[1]: https://cockpit-project.org/guide/latest/embedding.html "particular page frame"
+
+**cockpit-ws**(8), **cockpit-bridge**(1)