diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 6e46a6321..a79fa9bdb 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -125,8 +125,8 @@ Features detected, such as when a mistake in a key sequence leaves us stuck in a submenu, to make query blueprints easier to debug -Editing blueprints ------------------- +Creating blueprints +------------------- We recommend using a spreadsheet editor such as Excel, `Google Sheets `__, or `LibreOffice `__ @@ -281,7 +281,7 @@ Note that area expansion syntax can only specify rectangular areas. If you want to create extent-based structures (e.g. farm plots or stockpiles) in different shapes, use the first format above. For example:: - #place L shaped food stockpile + #place A single L shaped food stockpile f f ` ` # f f ` ` # f f f f # @@ -292,8 +292,8 @@ Area expansion syntax also sets boundaries, which can be useful if you want adjacent, but separate, stockpiles of the same type:: #place Two touching but separate food stockpiles - f(4x2) # - ~ ~ ~ ~ # + f(2x2) # + ~ ~ ` ` # f(4x2) # ~ ~ ~ ~ # # # # # # @@ -303,8 +303,8 @@ and can be used for visualizing the blueprint layout. This blueprint can be equivalently written as:: #place Two touching but separate food stockpiles - f(4x2) # - ~ ~ ~ ~ # + f(2x2) # + ~ ~ ` ` # f f f f # f f f f # # # # # # @@ -793,8 +793,8 @@ Start positions Start positions specify a cursor offset for a particular blueprint, simplifying the task of blueprint alignment. This is very helpful for blueprints that are -based on a central staircase, but it helps whenever a blueprint has an obvious -"center". For example:: +based on a central staircase, but it comes in handy whenever a blueprint has an +obvious "center". For example:: #build start(2;2;center of workshop) label(masonw) a mason workshop wm wm wm # @@ -850,130 +850,47 @@ The quotes surrounding the cell text are only necessary if you are writing a .csv file by hand. Spreadsheet applications will surround multi-line text with quotes automatically when they save/export the file. -.. _quickfort-packaging: - -Packaging a set of blueprints -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A complete specification for a section of your fortress may contain 5 or more -separate blueprints, one for each "phase" of construction (dig, build, place -stockpiles, designate zones, and query adjustments). - -To manage all the separate blueprints, it is often convenient to keep related -blueprints in a single file. For .xlsx spreadsheets, you can keep each blueprint -in a separate sheet. Online spreadsheet applications like `Google -Sheets `__ make it easy to work with multiple related -blueprints, and, as a bonus, they retain any formatting you've set, like column -sizes and coloring. - -For both .csv files and .xlsx spreadsheets you can also add as many blueprints -as you want in a single file or sheet. Just add a modeline in the first column -to indicate the start of a new blueprint. Instead of multiple .csv files, you -can concatenate them into one single file. This is especially useful when you -are sharing your blueprints with others. A single file is much easier to manage -than a directory of files. - -For example, you can store multiple blueprints together like this:: - - #dig label(bed1) - d d d d # - d d d d # - d d d d # - d d d d # - # # # # # - #build label(bed2) - b f h # - # - # - n # - # # # # # - #place label(bed3) - # - f(2x2) # - # - # - # # # # # - #query label(bed4) - # - booze # - # - # - # # # # # - #query label(bed5) - r{+ 3}& # - # - # - # - # # # # # - -Of course, you could still choose to keep your blueprints in single-sheet .csv -files and just give related blueprints similar names:: - - bedroom.1.dig.csv - bedroom.2.build.csv - bedroom.3.place.csv - bedroom.4.query.csv - bedroom.5.query2.csv - -The naming and organization is completely up to you. - -.. _quickfort-other-modes: - -Other blueprint modes -~~~~~~~~~~~~~~~~~~~~~ - -There are a few additional blueprint modes that become useful when you are -sharing your blueprints with others or managing complex blueprint sets. Instead -of mapping tile positions to keystroke sequences like the basic modes do, these -"blueprints" have specialized, higher-level uses: - -============== =========== -Blueprint mode Description -============== =========== -meta Link sequences of blueprints together -notes Display long messages, such as help text or blueprint - walkthroughs -aliases Define aliases that are visible only in the current file -ignore Hide a section from quickfort, useful for scratch space or - personal notes -============== =========== - .. _quickfort-meta: Meta blueprints -``````````````` +~~~~~~~~~~~~~~~ -Meta blueprints are blueprints that script a series of other blueprints. For -example, many blueprint sets follow this pattern: +Meta blueprints are blueprints that control how other blueprints are applied. +For example, meta blueprints can bundle a group of other blueprints so that they +can be run with a single command. They can also encode logic, like duplicating a +blueprint a specified number of times. -1. Apply dig blueprint to designate dig areas +A common scenario where meta blueprints are useful is when you have several +phases to link together. For example you might: + +1. Apply a dig blueprint to designate dig areas #. Wait for miners to dig -#. **Apply build buildprint** to designate buildings -#. **Apply place buildprint** to designate stockpiles -#. **Apply query blueprint** to configure stockpiles +#. **Apply a build buildprint** to designate buildings +#. **Apply a place buildprint** to designate stockpiles +#. **Apply a query blueprint** to configure stockpiles #. Wait for buildings to get built #. Apply a different query blueprint to configure rooms Those three "apply"s in the middle might as well get done in one command instead -of three. A ``#meta`` blueprint can encode that sequence. A meta blueprint -refers to other blueprints in the same file by their label (see the -`Modeline markers`_ section above) in the same format used by the `quickfort` -command: ``/