Fix #1827 -- human-written manpage

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Jun 23, 2015 · 2d4b05a45130ab2171feffb4bfa39f57f618e70c · 2d4b05a
1 parent 91113fc
commit 2d4b05a45130ab2171feffb4bfa39f57f618e70c
diff --git a/docs/man/nikola.1.gz b/docs/man/nikola.1.gz
diff --git a/docs/man/nikola.rst b/docs/man/nikola.rst
@@ -0,0 +1,120 @@
+  
+======
+  
+Nikola
+  
+======
+  
+
+  
+--------------------------------
+  
+A Static Site and Blog Generator
+  
+--------------------------------
+  
+
+  
+:Version: Nikola v7.5.1
+  
+:Manual section: 1
+  
+:Manual group: User Commands
+  
+
+  
+SYNOPSIS
+  
+========
+  
+
+  
+Create an empty site (with a setup wizard):
+  
+
+  
+    ``nikola init mysite``
+  
+
+  
+Create a post (inside the ``mysite`` directory):
+  
+
+  
+    ``nikola new_post``
+  
+
+  
+Build the site:
+  
+
+  
+    ``nikola build``
+  
+
+  
+Start the test server:
+  
+
+  
+    ``nikola serve``
+  
+
+  
+See the site:
+  
+
+  
+    ``xdg-open http://127.0.0.1:8000/``
+  
+
+  
+
+  
+DESCRIPTION
+  
+===========
+  
+
+  
+Nikola is a static website and blog generator. The very short
+  
+explanation is that it takes some texts you wrote, and uses them to
+  
+create a folder full of HTML files. If you upload that folder to a
+  
+server, you will have a rather full-featured website, done with little
+  
+effort.
+  
+
+  
+It's original goal is to create blogs, but it supports most kind of
+  
+sites, and can be used as a CMS, as long as what you present to the
+  
+user is your own content instead of something the user generates.
+  
+
+  
+Nikola can do:
+  
+
+  
+* A blog
+  
+* Your company's site
+  
+* Your personal site
+  
+* A software project's site
+  
+* A book's site
+  
+
+  
+Since Nikola-based sites don't run any code on the server, there is no
+  
+way to process user input in forms.
+  
+
+  
+Nikola can't do:
+  
+
+  
+* Twitter
+  
+* Facebook
+  
+* An Issue tracker
+  
+* Anything with forms, really (except for comments!)
+  
+
+  
+Keep in mind that "static" doesn't mean **boring**. You can have
+  
+animations, slides or whatever fancy CSS/HTML5 thingie you like. It
+  
+only means all that HTML is generated already before being uploaded.
+  
+On the other hand, Nikola sites will tend to be content-heavy. What
+  
+Nikola is good at is at putting what you write out there.
+  
+
+  
+COMMANDS
+  
+========
+  
+
+  
+The most basic commands needed to get by are:
+  
+
+  
+``nikola help``
+  
+    get a list of commands, or help for a command
+  
+``nikola version [--check]``
+  
+    print version number
+  
+``nikola init [-d|--demo] [-q|--quiet] folder``
+  
+    initialize new site
+  
+``nikola build``
+  
+    build a site
+  
+``nikola new_post``
+  
+    create a new post
+  
+``nikola new_page``
+  
+    create a new page
+  
+``nikola status [--list-drafts] [--list-modified] [--list-scheduled]``
+  
+    show site and deployment status
+  
+``nikola check [-v] (-l [--find-sources] [-r] | -f [--clean-files])``
+  
+    check for dangling links or unknown files
+  
+``nikola deploy [[preset [preset...]]``
+  
+    deploy the site using the ``DEPLOY_COMMANDS`` setting
+  
+``nikola github_deploy```
+  
+    deploy the site to GitHub Pages
+  
+``nikola serve [-p PORT] [-a ADDRESS] [-b|--browser] [-6|--ipv6]``
+  
+    start development web server
+  
+``nikola auto [-p PORT] [-a ADDRESS] [-b|--browser] [-6|--ipv6]``
+  
+    start development web server with automated rebuilds and reloads
+  
+``nikola plugin [options]``
+  
+    manage plugins from the Plugins Index
+  
+``nikola install_theme [name]``
+  
+    install themes from the Themes Index
+  
+
+  
+Use ``nikola help`` to get a list of all commands.
+  
+
+  
+BUGS
+  
+====
+  
+
+  
+Issue Tracker: https://github.com/getnikola/nikola/issues
+  
+
+  
+SEE ALSO
+  
+========
+  
+
+  
+* The Nikola Website: https://getnikola.com/
+  
+* Handbook: https://getnikola.com/handbook.html
+  
+* Support: https://getnikola.com/contact.html
diff --git a/docs/manual.txt b/docs/manual.txt
@@ -19,7 +19,7 @@ All You Need to Know
 After you have Nikola `installed <#installing-nikola>`_:
-  
-Create a empty site (with a setup wizard):
+  
+Create an empty site (with a setup wizard):
    ``nikola init mysite``
 You can create a site with demo files in it with ``nikola init --demo mysite``
@@ -31,6 +31,7 @@ Create a post:
 Edit the post:
    The filename should be in the output of the previous command.
+  
+    You can also use ``nikola new_post -e`` to open an editor automatically.
 Build the site:
     ``nikola build``
@@ -39,7 +40,7 @@ Start the test server:
     ``nikola serve``
 See the site:
-  
-     http://127.0.0.1:8000
+  
+     http://127.0.0.1:8000/
 That should get you going. If you want to know more, this manual will always be here
 for you.

diff --git a/nikola/plugins/command/auto/__init__.py b/nikola/plugins/command/auto/__init__.py
@@ -98,6 +98,7 @@ class CommandAuto(Command):
        {
            'name': 'browser',
            'short': 'b',
+  
+            'long': 'browser',
            'type': bool,
            'help': 'Start a web browser.',
            'default': False,

diff --git a/nikola/plugins/command/check.py b/nikola/plugins/command/check.py
@@ -94,7 +94,7 @@ class CommandCheck(Command):
    name = "check"
    logger = None
-  
-    doc_usage = "-l [--find-sources] | -f"
+  
+    doc_usage = "[-v] (-l [--find-sources] [-r] | -f [--clean-files])"
    doc_purpose = "check links and files in the generated site"
    cmd_options = [
        {

diff --git a/nikola/plugins/command/status.py b/nikola/plugins/command/status.py
@@ -39,6 +39,7 @@ class CommandDeploy(Command):
    doc_purpose = "display site status"
    doc_description = "Show information about the posts and site deployment."
+  
+    doc_usage = '[-l|--list-drafts] [-m|--list-modified] [-s|--list-scheduled]'
    logger = None
    cmd_options = [
        {

diff --git a/nikola/plugins/command/version.py b/nikola/plugins/command/version.py
@@ -40,7 +40,7 @@ class CommandVersion(Command):
    name = "version"
-  
-    doc_usage = ""
+  
+    doc_usage = "[--check]"
    needs_config = False
    doc_purpose = "print the Nikola version number"
    cmd_options = [

diff --git a/scripts/set_version.py b/scripts/set_version.py
@@ -10,6 +10,7 @@
 import sys
 import glob
 import subprocess
+  
+import io
 def sed_like_thing(pattern, repl, path):
@@ -35,5 +36,12 @@ def sed_like_thing(pattern, repl, path):
    sed_like_thing("release = .*", "release = '{0}'".format(version), os.path.join('docs', 'sphinx', 'conf.py'))
    sed_like_thing('__version__ = ".*"', '__version__ = "{0}"'.format(version), os.path.join('nikola', '__init__.py'))
    sed_like_thing('New in master', 'New in v{0}'.format(version), 'CHANGES.txt')
-  
-    subprocess.call(["help2man", "-N", "--version-string={0}".format(version), "-n", "static site and blog generator", "-o", os.path.join('docs', 'man', 'nikola.1'), "nikola"])
+  
+    sed_like_thing('Nikola v.*', 'Nikola v{0}'.format(version), os.path.join('docs', 'man', 'nikola.rst'))
+  
+    man = subprocess.check_output(["rst2man", os.path.join('docs', 'man', 'nikola.rst')])
+  
+    with io.open(os.path.join('docs', 'man', 'nikola.1'), 'w', encoding='utf-8') as fh:
+  
+        try:
+  
+            man = man.decode('utf-8')
+  
+        except AttributeError:
+  
+            pass
+  
+        fh.write(man)
    subprocess.call(["gzip", "-f", os.path.join('docs', 'man', 'nikola.1')])