1 About Draftman2

Draftman2 is an organizational tool I use for my long-form writing projects.

Features:

  1. Free and open source
  2. Minimalist
  3. Bring-your-own editor
  4. Markdown/plain-text based

The Draftman2 App Window

The Draftman2 App Window

2 Reporting bugs

If you find a bug in Draftman2, please visit my GitHub page and create a new issue, providing as much information as you can about how to reproduce the bug.

https://github.com/jsseidel/draftman2/issues

Or better yet, fix it yourself and give me a pull request!

3 Quickstart

If you're new to Draftman2, select Project->Create tutorial... and select a directory to hold it. Then, follow along in the Notes field.

4 Installing Draftman2

Draftman2 will run out-of-the-box in Ubuntu 18.04 and 20.04. Simply clone the repo and run draftman2_py_run.

On other distros, you might need to perform the equivalent of the following:

cd draftman2
sudo apt install debhelper libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-3.0 python3-gi python3-gi-cairo
pip install -r requirements.txt

5 Keeper

5.1 Introduction

The Keeper (short for Trapper Keeper, like the old notebooks some of us used in the 80's) is a tree-like view of all the files and folders that make up your writing project. Just how you use it is up to you, but the concepts are similar to those you are already familiar with:

  1. Files represent text.
  2. Folders hold text files.
  3. A 'trashcan' holds files you may or may not want to eventually delete.

5.2 The view

The Keeper presents your project's files and folders in rows. Draftman2 projects are linear. If you imagine a Draftman2 project as a single text file, items at the top of the view would appear at the top of the file and items at the bottom would appear at the end of the file.

5.2.1 Columns

5.2.1.1 Type

An icon designates what type of object the row represents:

  1. A file icon represents a text file in your project. (Files can contain other files -- see Advanced/Project Structure for more information.)
  2. A folder icon represents a folder in your project. Folders contain files and other folders.
  3. A trashcan icon is created whenever you create a new folder with the name "Trash." Trash folders can only be deleted by copying them into another Trash folder and emptying with a right click. You can permanently delete items in a Trash folder by right-clicking them and confirming.

5.2.1.2 Name

The name of the file or folder. Double-click in the name to rename a file.

5.2.1.3 Inc

The Inc check boxes indicate that the file or folder should be included when you Compile a Draftman2 project. See the Compiling a Project section for more information about compiling a project to a single file.

5.2.1.4 Scenes/Running

Scenes tells you how many 'scenes' are in a file or a folder represented by that row. Scenes, in Draftman2 parlance, indicate either a count of Markdown headers in a text file (i.e. lines beginning with #) or the file itself as a single scene. Because you might not use headers in a file, a file that contains no headers is counted as having one scene, even empty files. See the Project Organization section for more information.

The scene count next to a folder indicates the total number of scenes found within the folder. If you have a folder that contains five files with one scene per file, Scenes would be 5 at the folder row. If you open the folder, each file would show 1 scene at its row.

The Running column next to the Scenes column indicates how many total scenes that have been found as of and including that row for all included (Inc is checked) items above.

5.2.1.5 Words/Running

The Words and associated Running column are identical to the Scenes/Running columns, except they count words instead of scenes.

Similar to scenes, only included (Inc is checked) files are counted as part of a total count.

5.3 Rows

You can take specific action on rows by selecting them and right-clicking. Further, you can reorder rows by clicking and dragging.

You can de-select all rows by clicking in white space below all rows. This also refreshes the scene and word counts.

5.4 Status

Below the rows, there are several status items and a couple of buttons:

5.4.1 Words

The total words of all included objects in your project.

5.4.2 Scenes

The total number of included scenes in your project

5.4.3 Avg words/file

The average number of words per included file in your project. This can be used to predict your project's overall length if you have an idea of how many scenes your project will contain.

5.4.4 Update counts

After editing a file outside of Draftman2, click Update counts to update the number of words and scenes in the Keeper.

5.4.5 Expand all

Click Expand all to open all folders in the Keeper

5.4.6 Collapse all

Click Collapse all to close all folders in the Keeper

6 Notes

Every Draftman2 object, i.e. every file and folder, has an associated note. Notes are Markdown files saved in the 'notes' directory inside Draftman2 projects.

Why you might like this feature:

  1. If you're a plotter, you can create a bunch of chapter folders and empty scenes and use the notes to keep track of what each scene or chapter is about.
  2. As you're writing a scene, use a note to jot down problems or ideas you might think of as you're writing.
  3. Use notes to keep track of what needs editing as you're proofing or going over your story.

Note files are saved automatically whenever you change a selection or quit Draftman2.

7 Compiling a Project

To assemble all the relevant files into a coherent single Markdown document, select Compile... from the Project menu and then choose a location to store the file.

Draftman2 will include all files marked as Inc from the Keeper.

7.1 Include folder titles

In the Project->Preferences... dialog, select Include folder titles to tell Draftman2 to automatically include folder titles as in the output at the appropriate heading level.

7.2 Include file titles

Similarly, select Include file titles to tell Draftman2 to automatically include file titles in the output at the appropriate heading level.

7.3 Include text with files

If you need to include some arbitrary text before each file, like a * * * scene separator, select Include text with files and type in your text next to the check box. If, for some reason, you don't want to include that text after the first heading, as in the case of scene separators, click And skip first.

For more information about structuring your project to make consistent headings, see Project Organization.

8 Project Organization

Since Draftman2 was written primarily with fiction writers in mind, the following demonstrates how you might organize a novel draft.

Stick to the following conventions:

  1. Large groupings of Chapters, e.g. "Books", are represented by folders.
  2. Chapters are represented by folders.
  3. A single file contains a single scene.
  4. No headings at all are used in files.

In Preferences, uncheck Include file titles and check Include folder titles. Additionally, check Include text with files and add * * * to the text entry box to use as a scene separator. Check And skip first. Then, when you compile the project into a single Markdown, Draftman2 outputs the appropriate heading levels at the top of each file. For example, if you have a file named 'My scene' in a folder named 'Chapter 1' which is itself inside a folder named 'Book 1', the output will be something like this:

# Book 1

## Chapter 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et cursus orci. Nam dignissim maximus mauris, tincidunt ultricies leo congue a. Vivamus gravida venenatis feugiat. Quisque egestas diam in enim iaculis, quis fermentum enim commodo. Nunc tincidunt ante eget dui suscipit dictum. Aliquam mauris nibh, sollicitudin et elit ut, vestibulum viverra enim. Proin finibus malesuada tristique. Nunc venenatis tortor non mi tristique varius.

* * *

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et cursus orci. Nam dignissim maximus mauris, tincidunt ultricies leo congue a. Vivamus gravida venenatis feugiat. Quisque egestas diam in enim iaculis, quis fermentum enim commodo. Nunc tincidunt ante eget dui suscipit dictum. Aliquam mauris nibh, sollicitudin et elit ut, vestibulum viverra enim. Proin finibus malesuada tristique. Nunc venenatis tortor non mi tristique varius.

If you need individual scenes to have titles, check Include file titles in Preferences and uncheck Include text with files.

8.1 When titles aren't enough

So what do you do if a folder title isn't enough? Like, let's say you want to quote some song lyrics before your chapter. You could put them in at the top of your scene, but that's not ideal because they'll show up under the chapter heading and you want them before the chapter heading.

Here's another way of organizing your projects.

Start by unchecking both the Include file titles and Include folder titles in Preferences. Then,

  1. Add a new file where appropriate to your project and give it a name. Edit the file and paste in your lyrics and chapter heading.
  2. Right-click on the new file and select Add file...
  3. Add your scene heading (if any) and edit your scene file.
  4. Compile.

Here, you'll see something like this in the output:

And she's buying a stairway to heaven.
-- Led Zeppelin

# Chapter 1

## The big heist

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et cursus orci. Nam dignissim maximus mauris, tincidunt ultricies leo congue a. Vivamus gravida venenatis feugiat. Quisque egestas diam in enim iaculis, quis fermentum enim commodo. Nunc tincidunt ante eget dui suscipit dictum. Aliquam mauris nibh, sollicitudin et elit ut, vestibulum viverra enim. Proin finibus malesuada tristique. Nunc venenatis tortor non mi tristique varius.

The point is that sub-files are just like folders, except that Draftman2 outputs the contents of the file containing a sub-file in addition to any titles.

9 Menu

The following describe all the menu items in Draftman2.

9.1 File

9.1.1 Open project...

Open an existing Draftman2 project.

9.1.2 New project...

Create a new Draftman2 project. Draftman2 will create a new named directory containing the project files in the directory you choose.

9.1.3 Quit

Quit Draftman2

9.2 Project

9.2.1 Add file...

Add a file underneath the selected row.

9.2.2 Add folder...

Add a folder underneath the selected row.

9.2.3 Add file at root...

Add a new file to the project root.

9.2.4 Add folder at root...

Add a new folder to the project root.

9.2.5 Edit...

Edit the currently selected file using the editor defined in Project->Preferences...

9.2.6 Delete...

Delete the files associated with the selected row. Note that the delete is recursive, so deleting a folder will also delete everything inside the folder.

9.2.7 Compile...

Produces a single Markup file containing all the files marked for inclusion in the chosen oirectory.

9.2.8 Create backup

Generates a zip archive of the project directory and puts it in the backups directory defined in Project->Preferences...

9.2.9 Refresh file list/word counts

Recalculates the word and scene counts in the Keeper.

9.2.10 Preferences...

9.2.10.1 Application

Select the application Draftman2 should launch when you want to edit a file. The application must take at least one argument: the name of the file to edit.

9.2.10.2 Arguments

Any additional arguments required to launch the editor successfully. For example, to support a gvim writing configuration, you might choose something like the following as an argument to gvim:

-u /home/mylogin/.vimrc_for_writing_only

9.2.10.3 Include folder titles

Draftman2 will output the titles of folders using an appropriate heading level. For example, if a folder named 'My folder' is contained within a folder at the root folder, Draftman would output:

## My folder

9.2.10.4 Include file titles

Similar to folder titles, Draftman2 will output file titles, using a heading level determined by the number of parent folders.

9.2.10.5 Include text with files

Draftman2 will place the provided arbitrary text at the top of every included file in the compilation.

This is useful if you like to use scene separators like * * * or ~~~.

If you do not want to include the text after a heading, click the 'And skip first' checkbox. Then you'll end up with:

# Some heading

Some text.

Instead of:

# Some heading

* * *

Some text.

9.2.10.6 Backup automatically upon startup

Draftman2 will create a backup of your currently loaded project in the directory specified (see next item).

9.2.10.7 Directory

The directory to store your Draftman2 backups. This defaults to the project directory itself when the project is created.

9.3 About

Displays credits.

9.4 Create tutorial

Draftman2 will generate a tutorial and save it in a directory of your choosing.

10 Advanced

10.1 Project Structure

Draftman2 projects have the following structure:

Project Directory/
+--keeper
|   +-- <stripped file name 1>-YYYYMMDD_HHMMSS.md
|   +-- <stripped file name 2>-YYYYMMDD_HHMMSS.md
|   +-- <etc>
+--keeper.yaml
+--notes
    +-- <stripped file name 1>-YYYYMMDD_HHMMSS.md
    +-- <stripped file name 2>-YYYYMMDD_HHMMSS.md
    +-- <stripped folder name 1>-YYYYMMDD_HHMMSS.md
    +-- <etc>
    +-- trash-0.md

The time stamp is generated only once, when the file is created.

Every Draftman2 file has an associated file in "keeper" and "notes." Folder names are internal, but have an associated file in "notes."

File and folder names are created like this:

<lowercase name with punctuation stripped>-<YYYYMMDD_HHMMSS>.md

This structure makes all the file names unique, even if they have the same name.

10.1.1 keeper.yaml

keeper.yaml is a YAML file that acts as the project database. It looks like this:

project:
  editor: '/usr/bin/gedit'
  editorArgs: ''
  backupPath: '/home/att/backups'
  backupOnStart: False
  includeTitlesCompile: False
  includeDirectoryTitlesCompile: True
  includeTextCompile: False
  includeTextEntryCompile: ''
  skipFirst: False

keeper:
  - type: 'file'
    title: 'My File 1'
    id: '20191204_102120'
    compile: True
  - type: 'directory'
    title: 'My File 1'
    id: '20191204_102120'
    compile: True
    contents:
      - type: 'file'
        title: 'My Sub File 1'
        id: '20191204_102120'
        compile: True
  - type: 'file'
    title: 'My File 1'
    id: '20191204_102120'
    compile: True
     contents:
      - type: 'file'
        title: 'My Sub File 2'
        id: '20191204_102125'
        compile: True

Project preferences are stored at the top and the directories and files are stored on the bottom.

10.2 HiDPI

HiDPI (2K and 4K) can affect the way the Draftman2 Keeper appears. You can adjust the appearance with 2 environment variables:

DRAFTMAN2_ICON_SIZE=48
DRAFTMAN2_TREE_INDENT=5

The first, DRAFTMAN2_ICON_SIZE, determines how large or small the file, folder, and trash icons appear in the Keeper.

The second, DRAFTMAN2_TREE_INDENT, determines how much indentation happens at each level of the Keeper.

You can either add these to your normal login environment or activate them upon launching Draftman2 in a draftman2.desktop file in Gnome-based distros or editing your application menu in KDE-based environments.

In other environments, you launch Draftman2 like this, with or without the environment variables, suitable for the command line or adding to the desktop file or a command field:

DRAFTMAN2_ICON_SIZE=48 DRAFTMAN2_TREE_INDENT=10 /opt/draftman2/draftman2_run
Powered by MkTechDocs