JD index text format - ideas and comments, please

[johnnydecimal]

The problem

You need an index of your items. I bang on about this on the site, and I really mean it. Why?

@professorbananas

So basically, my question is: how would you go about consolidating the info stored across all of these platforms, tools and media? I’ve been thinking about storing as much as possible in folders on my Mac or in the cloud, even images from Pinterest, but this perhaps defeats the purpose of such tools.

My system shouldn’t restrict where you keep things or what tools or sites you use. But this is where an index is critical, and this demonstrates why really nicely.

The (suggested) solution

First, the solution. And this is the endorsed-by-JD, will-be-supported-by-software format. Do this:

10-19 Area whatever
   11 Category you-know-what
   11.01 My item in one place
   - Location: Pinterest[1]
   11.02 My item in another place
   - Location: Google Drive
   11.03 One more item
   - Location: MacBook/~

[1]: And you’ll be able to [markdown](URL here) format links here so that they become clickable.

You could also leave yourself a note against any item.

   11.04 My item
   - Note: Whatever I want to remember.

Basically after any item you can enter - [Key]: [Value] and that’ll be valid.

Comments, please

Can this thread become the place where we talk about, wish for, criticise, find problems with, pick apart, find the bugs, etc., in my suggested canonical JD text index format.

I’ll document that format more formally shortly. I’m still drinking my morning tea.

[jack.baty]

I like the idea of having a “blessed” format, especially once tooling is involved. If I were more ambitious, I would write an Emacs mode for it. On the other hand, I’ve already considered doing it right in Org mode instead, since that’s already an outliner.

But yeah, a text-based format will do nicely.

[johnnydecimal]

Here’s my current thinking. I’ll keep this post as the one single record for this, but if I update it I’ll pop a reply at the bottom. (Unless you Discourse veterans have a better way? Lemme know.)

Current status of this post: started, i.e. not finished!

Goals

1. Allow people to keep an ‘index’ of their JD system. It must allow for the full PRO.AC.ID format if required.
2. Be able to be used without any extra tools, i.e. in any text editor.
   a. Be useable as the index in its raw form, i.e. be formatted in a way that makes it immediately useable.
3. Be trivially transferable, i.e. be copy-pasteable to any other tool.
4. Be machine-parseable so you can use software if you want. That might be mine, your own, someone else’s, whatever.

Solution

1. Plain-text.
2. The language defines itself because of the structured nature of the JD numbers.

AC.ID format

10-19 This is an area (x0-x9)
   10 This is a category (xy, where x matches the area above)
      10.01 This is an ID (xy.id), where xy matches the category above)

PRO.AC.ID format

100 This is a project (zzz)
    10-19 This is an area (x0-x9)
       10 This is a category (xy, where x matches the area above)
          10.01 This is an ID (xy.id), where xy matches the category above)
101 This is the next project
    // ...and so on

3. Categories must ‘belong’ to their parent area, and IDs must ‘belong’ to their parent categories.
4. Numbers may not duplicate; if there are duplicates, the file is invalid.
5. Numbers must be in order; if they are out of order, the file is invalid.
6. Numbers may be skipped. Category 13 may directly follow 11.
7. Whitespace is optional. Any given tool may format for you, as shown above, but it is semantically meaningless.
8. Additional metadata may be specified on any item as follows:

100 This is a project // or any other type of item
- Note: This is a note
- Location: This is a location [1]
- Anything else: This is any other text

[1]: Markdown-style hyperlinks []() are supported in metadata text.

The format is as follows:

• A single dash symbol. (Must be the dash, whatever the Unicode is.)
• A space.
• The name of the ‘key’, e.g. ‘Note’.
  • This may include spaces but obviously may not include…
• A colon.
• A space.
• The ‘value’, e.g. ‘This is my note’.

Note that the Markdown-link-style is supported but it is up to any given implementation whether to do anything with it.

9. Blank lines are ignored (but should be kept by any parser — if the user wants them, don’t remove them).
10. Markdown-style dividers are supported: three or more hyphens, asterisks, or underscores on a line by themselves.
11. JavaScript-style inline comments are supported after an item, e.g.
    11 My category // This is a comment.

• In this case the item is 11 My category and This is a comment is recorded as an inline comment.
• The multi-line syntax /* comment */ is not supported. (Should it be?)

---

That’ll do for a start, I have to head out. Initial thoughts? Please pick this apart, what have I missed?

Edit: added 11.
Edit: added 2.a.

[bbfile]

The recfile format is another option. It’s plain text and very readable and there are free tools for querying/updating the content if you want to automate something.

[johnnydecimal]

Interesting, thanks for the link. I don’t think that’ll work, however, because you made me realise what I missed…

I’m just about to add 2.a. to the Goals above:

2.a. Be useable as the index in its raw form, i.e. be formatted in a way that makes it immediately useable.

Recfile doesn’t do that, but I can see myself using it for other things at work. Looks neat.

[bbfile]

As I was writing it I did think, “Oh this doesn’t look like a tree”, but good to bounce ideas around anyway. I’m currently putting all my comic books in a recfile so it’s on my mind

[johnnydecimal]

All the ideas help, I want all the ideas please.

[dixonge]

I’ve just been banging my head against the Hazel rules wall in order to try and create a dynamically updating index list in plain text. So far a solution has completely eluded me. Rules such as ‘when name changes’ do not even seem to work. Bash scripts work, if I can come up with the appropriate regex-fu, but I’m unsure how to trigger them based on a folder being added, removed, moved or renamed.

Any ideas?

[bbfile]

I haven’t tried it, but I had considered using watchman to do something like this.

The quickstart example on the main page seems like a similar case:

These two lines establish a watch on a source directory and then set up a trigger named buildme that will run a tool named minify-css whenever a CSS file is changed. The tool will be passed a list of the changed filenames.
$ watchman watch ~/src
$ watchman – trigger ~/src buildme ‘*.css’ – minify-css

[johnnydecimal]

Oh, interesting. I’ll have a look at that … sounds similar to the thing I built for work last week which takes a DOS dir /b /s /a:d output and turns it in to HTML which you paste in to a SharePoint wiki page. Hang on while I sanitise and upload for anyone interested…

Here we go: github/johnnydecimal/sharepoint-decimaliser-sanitised. Hideous code but it might inspire someone.

This has me thinking though, maybe I should write some sort of command-line thing using deno.

[Angelo]

Hello! New to the forum and the system, but reading the first post in this topic, it struck me that it looks similar to the TaskPaper format, or, more broadly, OPML (on which TaskPaper’s format is based, IIRC?).

The nice thing about OPML is that it’s meant to be fully transportable between any outlining software, and the nested folders of the Johnny.Decimal system are exactly that: an outline. Here’s a sample “directory” OPML file that could be a jumping off point, for example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<opml version="2.0">
	<head>
		<title>JohnnyDecimalIndex.opml</title>
	</head>
	<body>
		<outline text="Johnny Decimal Index"/>
			<outline text="100-199 Personal" type="link" url="file:///Users/Angelo/Documents/100-199 Personal"/>
			<outline text="200-299 Business" type="link" url="file:///Users/Angelo/Documents/200-299 Business"/>
			<!-- Not going the full PRO.AC.ID depth, but you get the idea -->
	</body>
</opml>

Having a url property means it can point to web addresses, or even any file/app with a URL scheme (e.g., mindnode://open?name=JohnnyDecimaSystem.mindnode).

The not-so-nice thing about OPML is that it’s based on XML, so… it’s not exactly human-readable. But it’s trivial for software to parse, is already widely supported by outliners and feed-readers, and has been around for over a decade, so there are a tonne of libraries for reading/writing OPML in whatever programming/scripting language.

[johnnydecimal]

I like the principle, hate the XML. But it’s a good idea: ensure that the human-readable, daily-use JD format can be automatically parsed by a dingus in to XML. There’s nothing in the human form that can’t be expressed in the XML form.

Then if you need one or the other, you just run your system either way through the translator (which could just be an API on the ‘net somewhere, Netlify Functions or what have you).

[Angelo]

Yeah, pretty sure XML stands for “eXcruciating Markup Language”.