Markdown.lua - Steam version update

docs/markdown.rst

@@ -2,56 +2,98 @@ markdown
 ========
 
 .. dfhack-tool::
-    :summary: Exports the text you see on the screen for posting online.
-    :tags: unavailable
-
-This tool saves a copy of a text screen, formatted in markdown, for posting to
-Reddit (among other places). See `forum-dwarves` if you want to export BBCode
-for posting to the Bay 12 forums.
-
-This script will attempt to read the current screen, and if it is a text
-viewscreen (such as the dwarf 'thoughts' screen or an item 'description') then
-append a marked-down version of this text to the output file. Previous entries
-in the file are not overwritten, so you may use the ``markdown`` command
-multiple times to create a single document containing the text from multiple
-screens, like thoughts from several dwarves or descriptions from multiple
-artifacts.
-
-The screens which have been tested and known to function properly with this
-script are:
-
-#. dwarf/unit 'thoughts' screen
-#. item/art 'description' screen
-#. individual 'historical item/figure' screens
-#. manual pages
-#. announcements screen
-#. combat reports screen
-#. latest news (when meeting with liaison)
-
-There may be other screens to which the script applies. It should be safe to
-attempt running the script with any screen active. An error message will inform
-you when the selected screen is not appropriate for this script.
+    :summary: Save description of selected unit/item in Markdown file
+    :tags: dfhack | items | units
+
+Saves the description of a selected unit or item to a Markdown file encoded in UTF-8.
+
+By default, data is stored in the `Dwarf Fortress/markdown_{YourWorldName}.md`
+file in the root game directory.
+
+For units, the script retrieves:
+#. Name, race, age, profession
+#. Description from the Unit/Health/Description screen
+#. Traits from the Unit/Personality/Traits screen
+The script tested on dwarves, dogs, elves, goblins, beasts,
+and is expected to work with all units
+
+For items, it retrieves:
+#. Decorated name (e.g., "☼«☼Chalk Statue of Dakas☼»☼")
+#. Full description from the item's view sheet
+The script works for most items with in-game descriptions and names, including those in storage,
+on the ground, installed as a building, or worn/carried by units.
+
+By default, entries are appended, not overwritten, allowing the ``markdown`` command
+to compile descriptions of multiple items & units in a single document.
 
 Usage
 -----
 
 ::
 
-    markdown [-n] [<name>]
+    markdown [-o | --overwrite] [<filename>]
+
+Appends the description of the selected unit/item
+to ``markdown_{world_name}.md`` file by default.
+Specifying a filename will append to ``markdown_{filename}.md`` instead,
+which is useful for organizing data by category or topic.
+The [-o] argument tells the script to overwrite the output file.
+
+Options
+-------
 
-The output is appended to the ``md_export.md`` file by default. If an alternate
-name is specified, then a file named like ``md_{name}.md`` is used instead.
+``-o``, ``--overwrite``
+    Overwrite the output file, deleting previous entries.
 
 Examples
 --------
 
-``markdown``
-    Appends the contents of the current screen to the ``md_export.md`` file.
-``markdown artifacts``
-    Appends the contents of the current screen to the ``md_artifacts.md`` file.
+::
 
-Options
--------
+    markdown
+
+Example output for a selected chalk statue in the world "Orid Tamun", appended to the default ``markdown_Orid_Tamun.md`` file:
+
+    [...previous entries...]
+
+    ### ☼Chalk Statue of Bìlalo Bandbeach☼
+
+    #### Description:
+    This is a well-crafted chalk statue of Bìlalo Bandbeach. The item is an image of
+    Bìlalo Bandbeach the elf and Lani Lyricmonks the Learned the ettin in chalk by
+    Domas Uthmiklikot. Lani Lyricmonks the Learned is striking down Bìlalo Bandbeach.
+    The artwork relates to the killing of the elf Bìlalo Bandbeach by the
+    ettin Lani Lyricmonks the Learned with Hailbite in The Forest of Indignation in 147.
+
+    ---
+::
+
+    ``markdown -o descriptions``
+
+Example output for a selected unit Lokum Alnisendok, written to the newly overwritten ``markdown_descriptions.md`` file:
+::
+
+    ### Lokum Alnisendok, dwarf, 27 years old Presser.
+
+    #### Description:
+    A short, sturdy creature fond of drink and industry.
+
+    He is very quick to tire.
+
+    His very long beard is neatly combed.  His very long sideburns are braided.
+    His very long moustache is neatly combed.  His hair is clean-shaven.  He is average in size.
+    His nose is sharply hooked.  His nose bridge is convex.  His gold eyes are slightly wide-set.
+    His somewhat tall ears are somewhat narrow.  His hair is copper.  His skin is copper.
+
+    #### Personality:
+    He has an amazing memory, but he has a questionable spatial sense and poor focus.
+
+    He doesn't generally think before acting.  He feels a strong need to reciprocate any favor done for him.
+    He enjoys the company of others.  He does not easily hate or develop negative feelings.  He generally
+    finds himself quite hopeful about the future.  He tends to be swayed by the emotions of others.
+    He finds obligations confining, though he is conflicted by this for more than one reason.  He doesn't
+    tend to hold on to grievances.  He has an active imagination.
+
+    He needs alcohol to get through the working day.
 
-``-n``
-    Overwrite the contents of output file instead of appending.
+    ---