Markdown.lua - Steam version update

changelog.txt

@@ -28,6 +28,7 @@ Template for new versions:
 
 ## New Tools
 - Validated for adventure mode: `gui/sandbox`, `gui/create-item`
+- `markdown`: (reinstated) export unit or item descriptions to a markdown text file
 
 ## New Features
 - `instruments`: new subcommand ``instruments order`` for creating instrument work orders
@@ -47,6 +48,7 @@ Template for new versions:
 - `deathcause`: automatically choose a corpse when a pile of items is selected
 - `gui/quantum`: add option for whether a minecart automatically gets ordered and/or attached
 - `gui/quantum`: when attaching a minecart, show which minecart was attached
+- `markdown`: new keybinding for triggering text export: Ctrl-t
 
 ## Removed
 

docs/markdown.rst

@@ -2,56 +2,124 @@ 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: Export displayed text to a 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 ``markdown_{YourWorldName}.md`` file in the
+root of the game directory.
+
+For units, the script exports:
+
+#. Name, race, age, profession
+#. Description from the unit's Health -> Description screen
+#. Traits from the unit's Personality -> Traits screen
+
+For items, it exports:
+
+#. 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.
+You can quickly export text for the currently selected unit or item by tapping
+the Ctrl-t keybinding or selecting `markdown` from the DFHack logo menu.
 
 Usage
 -----
 
 ::
 
-    markdown [-n] [<name>]
+    markdown [<name>] [<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.
+Specifying a name will append to ``markdown_{name}.md``, which can be useful
+for organizing data by category or topic. If ``name`` includes whitespace,
+quote it in double quotes.
+
+If no ``name`` is given, the name of the loaded world is used by default.
 
 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.
+- ``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.
+
+    ---
 
 Options
 -------
 
-``-n``
-    Overwrite the contents of output file instead of appending.
+``-o``, ``--overwrite``
+    Overwrite the output file, deleting previous entries.
+
+Setting up custom keybindings
+-----------------------------
+
+If you want to use custom filenames, you can create your own keybinding so
+you don't have to type out the full command each time. You can run a command
+like this in `gui/launcher` to make it active for the current session, or add
+it to ``dfhack-config/init/dfhack.init`` to register it at startup for future
+game sessions::
+
+    keybinding add Ctrl-Shift-S@dwarfmode/ViewSheets/UNIT|dwarfmode/ViewSheets/ITEM "markdown descriptions"
+
+You can use a different key combination and output name, of course. See the
+`keybinding` docs for more details.
+
+Alternately, you can register commandlines with the `gui/quickcmd` tool and run
+them from the popup menu.