= New Help System for port(1) =

== Abstract == #abstract

The current help system in `port(1)` is very weak. The man pages are written in old roff format which is difficult to maintain and got neglected for a long time. Therefore this document proposes to develop a new help system for `port(1)` which will make it both easier for users to access the help and for developers to write and maintain documentation.

== Overall Status == #status

The new-help-system was merged to trunk in r123002.

== Details == #details

The new help system will make use of [http://www.methods.co.nz/asciidoc/ asciidoc] which is already used in other Open Source projects such as git and mercurial. Existing man pages of these projects can serve as reference for ours. Using asciidoc allows to generate multiple output formats out of one single source; especially interesting for us are man pages and !DocBook XML. The resulting man page can be included in the base distribution, while the !DocBook XML could help to integrate the man pages into the guide.

Asciidoc is already available in MacPorts and therefore easily accessible to all developers.

== Help invocation from port(1) == #invocation

As previous calls for participation to enhance `port help` went unheard, here is a proposal for a totally different system inspired by git. The documentation will be available as man pages, therefore `port help <topic>` will become an alias of `man port-<topic>`. This means it can be easily accessed from the command line. Once the man pages are also available online, a new switch `port help --web <topic>` could open the requested topic in the browser instead for users preferring websites over man pages.

Man pages will at least exist for all port commands, which will go into the man1 category. Some similar port commands should be covered by the same man page, such as activate/deactivate, archive/unarchive, etc. Splitting out certain topics from the current port(1) into their own man page to provide more details and examples will be considered; these will go into the man7 category.

== Changes for base developers == #developers

As asciidoc is not available on Mac OS X systems without installing MacPorts we should not add it as a new dependency for building base. Therefore, the generated man pages will be checked into SVN in the same manner we already do for the `configure` script and other files generated by autoconf. Man pages will still reside in the `base/doc` directory.

== References ==

 * [http://www.methods.co.nz/asciidoc/userguide.html Official AsciiDoc User Guide]
 * [http://powerman.name/doc/asciidoc AsciiDoc cheat sheet]
 * [http://asciidoctor.org/docs/asciidoc-writers-guide/ AsciiDoc Writer's Guide]
 * [http://git.kernel.org/?p=git/git.git;a=tree;f=Documentation Git man pages]

== Development Branch == #branch

These features will be developed on [browser:branches/new-help-system the new-help-system branch] before being merged back to trunk. Depending on the progress of the manpage writing it will target 1.10.0 or a later release.

== Current Status ==

=== man1 ===

Already done:
 * port.1
 * port-activate.1
 * port-archive.1
 * port-archivefetch.1
 * port-build.1
 * port-cat.1
 * port-cd.1
 * port-checksum.1
 * port-clean.1
 * port-configure.1
 * port-contents.1
 * port-deactivate.1
 * port-destroot.1
 * port-edit.1
 * port-extract.1
 * port-fetch.1
 * port-help.1
 * port-install.1
 * port-patch.1
 * port-rev-upgrade.1
 * port-selfupdate.1
 * port-uninstall.1

Still missing:

 * port-dependents
 * port-deps
 * port-dir
 * port-distcheck
 * port-distfiles
 * port-dmg
 * port-dpkg
 * port-echo
 * port-ed
 * port-exit
 * port-file
 * port-gohome
 * port-info
 * port-installed
 * port-lint
 * port-list
 * port-livecheck
 * port-load
 * port-location
 * port-mdmg
 * port-mirror
 * port-mpkg
 * port-notes
 * port-outdated
 * port-pkg
 * port-platform
 * port-portpkg
 * port-provides
 * port-quit
 * port-rdependents
 * port-rdeps
 * port-rpm
 * port-search
 * port-select
 * port-srpm
 * port-submit
 * port-sync
 * port-test
 * port-trace
 * port-unload
 * port-upgrade
 * port-url
 * port-usage
 * port-variants
 * port-version
 * port-work

=== man5 ===

Already done:
 * macports.conf

Missing:
 * sources.conf
 * variants.conf
 * pubkeys.conf

=== man7 ===

Already done:
 * portundocumented.7

Missing:
 * portfile
 * port-interactive
 * port-dev-style
 * port-dev-groups
  * port-dev-groups-python
  * port-dev-groups-perl
  * port-dev-groups-xcode
  * port-dev-groups-select
  * ...
 * port-hier
 * port-pseudo-ports
 * port-local-repository