Browse Source

Update manpage, and switch to asciidoctor for rendering

Christoph Biedl 3 years ago
parent
commit
b4c43ab1ae
5 changed files with 196 additions and 59 deletions
  1. 1 1
      debian/control
  2. 1 1
      debian/patches/upstream.typos.patch
  3. 1 1
      debian/rules
  4. 193 0
      debian/ykushcmd.1.adoc
  5. 0 56
      debian/ykushcmd.md

+ 1 - 1
debian/control

@@ -5,8 +5,8 @@ Standards-Version: 4.5.1
 Vcs-Browser: https://git.in-ulm.de/cbiedl/ykush-control
 Vcs-Git: https://git.in-ulm.de/cbiedl/ykush-control.git
 Build-Depends: debhelper-compat (= 13),
+    asciidoctor,
     libusb-1.0-0-dev,
-    pandoc,
 Priority: optional
 Rules-Requires-Root: no
 Section: utils

+ 1 - 1
debian/patches/upstream.typos.patch

@@ -1,4 +1,4 @@
-Description: Fix a typo
+Description: Typo fixes
 Author: Christoph Biedl <debian.axhn@manchmal.in-ulm.de>
 Date: 2020-12-20
 Bug: https://github.com/Yepkit/ykush/issues/31

+ 1 - 1
debian/rules

@@ -10,5 +10,5 @@ override_dh_auto_clean:
 	-rm debian/ykushcmd.1
 
 override_dh_installman:
-	pandoc --standalone --to man debian/ykushcmd.md -o debian/ykushcmd.1
+	asciidoctor --attribute reproducible --backend=manpage debian/ykushcmd.1.adoc
 	dh_installman

+ 193 - 0
debian/ykushcmd.1.adoc

@@ -0,0 +1,193 @@
+YKUSHCMD(1)
+===========
+:doctype: manpage
+
+== NAME
+
+ykushcmd - control application for Yepkit YKUSH Switchable USB Hub board
+
+
+== SYNOPSIS
+
+*ykushcmd* [board_name] [*-s* _serial_number_] [OPTIONS] ...
+
+
+== DESCRIPTION
+
+*ykushcmd* allows you to control the ports of a Yepkit YKUSH
+Switchable USB Hub board.
+
+=== Board names
+
+ ykush          YKUSH board
+ ykush3         YKUSH3 board
+ ykushxs        YKUSHXS board
+
+The [board_name] must be provided for commands addressed for a specific
+board.
+
+For general or common commands, applicable to all board models, the
+[board_name] has to be omited from the command.
+
+
+=== YKUSH board options
+
+*-d* 1|2|3|a
+
+  Power Down/Off downstream port with the number privided.
+
+  If [a] is provided as the port number then all ports will be switched.
+
+*-u* 1|2|3|a
+
+  Power Up/On downstream port number downstream_number
+
+*-s* serial_number
+
+  Board serial number to which the command is addressed.
+
+  When multiple YKUSH boards are connected to a host, this option
+  should be used to specify the board. If more than one board is
+  connected and this option is not provided the command will be sent to
+  the first board in the USB enumeration list.
+
+*-l*
+
+  Lists the serial numbers of the YKUSH boards attached to the host.
+
+*-g* 1|2|3
+
+  Show state of a downstream port.
+
+*-h*
+
+  Display help for YKUSH board specific commands.
+
+=== YKUSH3 board options
+
+*-d* 1|2|3|a
+
+  Power Down/Off downstream port with the number privided.
+
+  If [a] is provided as the port number then all ports will be
+  switched.
+
+*-u* 1|2|3|a
+
+  Power Up/On downstream port number downstream_number
+
+*-s* serial_number
+
+Board serial number to which the command is addressed.
+
+  When multiple YKUSH boards are connected to a host, this option
+  should be used to specify the board. If more than one board is
+  connected and this option is not provided the command will be sent to
+  the first board in the USB enumeration list.
+
+*-l*
+
+  Lists the serial numbers of the YKUSH boards attached to the host.
+
+*-g* 1|2|3
+
+  Show state of a downstream port.
+
+*-c* <port-number> <config-value>
+
+  Configure the default state of a downstream port
+  (port-number=1|2|3|e) at power-on. The port number <e> refers to
+  exteranl 5V port.
+
+  The default states are off (config-value=0), on (config-value=1) and
+  persistent (config-value=2).
+
+*-on*
+
+  Switch On the 5V output power port.
+
+*-off*
+
+  Switch Off the 5V output power port.
+
+*-r* 1|2|3
+
+  Read GPIO with the number provided (1, 2 or 3).
+
+*-w* 1|2|3 0|1
+
+  Write to the GPIO with the number provided (1, 2 or 3).
+
+  Writing a value of 1 or 0 will drive the GPIO to logical high or low,
+  respectively.
+
+*--gpio* enable|disable
+
+  Enable / Disable GPIO control interface. Will become active on next
+  reset/power-on.
+
+*--reset*
+
+  Resets (reboot) the YKUSH3 board.
+
+*-h*
+
+  Display help for YKUSH board specific commands.
+
+*--bootloader-version*
+
+  Board bootloader version.
+
+*--firmware-version*
+
+  Board firmware version.
+
+*--boot*
+
+  Enter bootloader mode for firmware update.
+
+=== YKUSHXS board options
+
+*-d*
+
+  Power Down/Off the downstream port.
+
+*-u*
+
+  Power Up/On the downstream port
+
+*-s* serial_number
+
+  Board serial number to which the command is addressed.
+
+  When multiple YKUSHXS boards are connected to a host, this option
+  should be used to specify the board. If more than one board is
+  connected and this option is not provided the command will be sent to
+  the first board in the USB enumeration list.
+
+*-l*
+
+  Lists the serial numbers of the YKUSHXS boards attached to the host.
+
+*-g*
+
+  Show state of the downstream port.
+
+*-h*
+
+  Display help for YKUSHXS board specific commands.
+
+
+== BUGS
+
+See GitHub issues: <https://github.com/Yepkit/ykush/issues>
+
+
+== COPYRIGHT AND LICENSE
+
+*ykush* is Copyright (c) 2017 Yepkit Lda and is licensed under the
+Apache License, Version 2.0.
+
+This manpage, base on the command line help, was written by Christoph
+Biedl <debian.axhn@manchmal.in-ulm.de> for the Debian project but may
+be used by others.

+ 0 - 56
debian/ykushcmd.md

@@ -1,56 +0,0 @@
-% YKUSHCMD(1) ykushcmd User Manual | ykushcmd
-
-# NAME
-
-**ykushcmd** - Control application for Yepkit YKUSH Switchable USB Hub board
-
-# SYNOPSIS
-
-| **ykushcmd** [**-l**] [**-d** _port_] [**-u** _port_] [**-g** _port_] [**-s** _serial_]
-
-# DESCRIPTION
-
-**ykushcmd** allows you to control the ports of a Yepkit YKUSH
-Switchable USB Hub board.
-
-## Options
-
-Ports numbers start with "1".
-
-**-l**
-  ~ List all currently attached YKUSH boards.
-
-**-d** _port_
-
-  ~ Turn the given port down/off.
-
-**-u** _port_
-
-  ~ Turn the given port up/on.
-
-**-d** _port_
-
-  ~ Get the switching status of the given port.
-
-**-s** _serial_
-
-  ~ Select the board by serial number. Needed if there's more than
-    one board connected.
-
-
-Using "a" as _port_ will affect all ports.
-
-# BUGS
-
-See GitHub Issues: <https://github.com/Yepkit/ykush/issues>
-
-If no board is detected, **ykushcmd -g a** will show one board with all
-three ports in status **UNKNOWN**.
-
-# COPYRIGHT & LICENSE
-
-**ykush** is Copyright (c) 2016 Yepkit Lda and is licensed under MIT
-license.
-
-This manpage was written by Christoph Biedl <debian.axhn@manchmal.in-ulm.de>
-for the Debian project but may be used by others.