Work in progress

Work in progress

 cljoly/hmrc2ledger

Disclaimer: This is not financial advice. It may be outdated or wrong, do your own research.

Convert CSV to ledger price db, to compute foreign transaction CGT (and section 104 holdings).

If you are using Ledger or one of its variants for your plain text accounting, you get to manage your finances a bit more like you manage code. With plain text files, in your favorite editor.

And yet, as opposed to code in most languages, you don’t have a Language Server Protocol implementation. So it’s a bit harder to get completions on accounts, tags, payees… You have to rely on bespoken support from your editor and that’s often imperfect or slow. Plus, if you declare your accounts and payees, you also can’t jump to the definition easily.

Enter ctags configuration for ledger, which this project provides. It generates tag file that’s understood by your editor, often out of the box (vim/neovim, emacs) or with a generic plugin (Atom, VS Code, TextMate and more). Congrats, your editor now has very fast completions and code navigation!

Installation

You need to have ctags installed¹.

Then drop ledger.ctags in ~/.config/ctags (or whatever ctags is configured to read).

Usage

ctags my/ledger/journal.ldg

will collect all the elements formally declared in the journal file. This means that in the following file:

tag UUID
account Assets
payee Shop
commodity EUR

2022-01-01 * Someone
    Expenses:Food   $10
    Liabilities:Credit Card

only UUID, Assets, Shop and EUR are detected, because they are the only one declared and so the only ones with a definition to jump to. Someone, Expenses, Expenses:Food, $, Liabilities and Liabilities:Credit Card are not declared, so they are ignored by ctags.

Initial List of Accounts, Payees…

As mentioned, ctags only collects elements that are declared. You could write the declarations manually, if you want to have fine-grained control of which accounts you want to actively use and have completions for. But to ease initial bootstrapping, you may want to start by adding everything you currently use in your ledger journals. You can do that with a couple commands.

For accounts, you can use this bash snippet:

ledger accounts | awk '{ print "account", $0}'

For payees:

ledger payees | awk '{ print "payee", $0}'

For tags:

ledger tags | awk '{ print "tag", $0}'

The snippets above output proper ledger definitions for accounts, payees and tags. You can insert these outputs in your journal or in a separate file with all your declarations (say declarations.ledger), that you can then include in your main journal file.

Don’t forget that ctags does not follow includes, so you should pass the file with the definitions to ctags (e.g. ctags declarations.ledger)

Multiple files

If you have multiple ledger journal files, pass them all to ctags (e.g. ctags *.ledger *.ldg) or run it on the current directory:

ctags -R .

Automatic Update with Chezmoi

Chezmoi external feature allows you to auto update and manage the ledger.ctags file, by adding the following to your ~/.local/share/chezmoi/.chezmoiexternal.toml:

[".config/ctags/"]
    type = "archive"
    include = [ "*/ledger.ctags" ]
    url = "https://github.com/cljoly/ledger.ctags/archive/master.zip/"
    stripComponents = 1

Contributing

Contributions (documentation or code improvements in particular) are welcome, see contributing!

Feel free to fill an issue if your declared accounts, tags, payee, alias… are not properly detected.

Acknowledgments

I would like to thank the creators, and all the contributors, of ctags and ledger. This is small configuration to make these two great projects work better together.

 cljoly/readme-in-static-site

This fast script allows you to insert your GitHub README in your static site and apply transformations. For instance, you can read this README on GitHub and on my website.

Why?

The GitHub README of your repo needs to efficiently describe your project to GitHub’s visitor. But featuring your project on your website allows you to (among other things):

• have more control on the theme and layout,
• insert scripts that GitHub would prohibit (like asciinema),
• have your project’s homepage independent of your hosting platform, if you wish to change at some point.

Chances are that for small projects, the page about your project is very similar to the GitHub README. Don’t duplicate efforts, describe the differences! This has been a long-awaited feature, in one form or another.

See this blog post for more details.

Testimonials

RISS made it to the first page of HackerNews and Lobsters and got comments like:

southerntofu

hannu

lifthrasiir

Run It (Nothing to Install)

To try it with Hugo or Zola, run the following in your static-site sources:

wget https://cj.rs/riss.awk
awk -f riss.awk /path/to/my-project/README.md > content/my-project.md

If you don’t use Hugo or Zola, no problem! It should also work with any markdown-based static-site generator. Just put the markdown file where it makes sense for that generator.

To automatically update these files in your static-site sources, see Automate with GitHub Actions below. Since RISS is based on Awk, there is nothing to install, besides copying the script itself!

Example

Add a Front Matter

Most static site generators require a “front matter” at the beginning of a markdown file to attach some metadata. But you don’t want to add this to your GitHub README! Let’s hide this on GitHub and have it in the script’s output.

In you .md file on GitHub, put:

<!-- insert
---
title: "README In Static Site (RISS)"
date: 2021-08-21T10:15:54
---
end_insert -->
<!-- Powered by https://cj.rs/riss -->
<!-- remove -->

# README In Static Site (RISS)
<!-- end_remove -->

The output of the script will be:

---
title: "README In Static Site (RISS)"
date: 2021-08-21T10:15:54
---
<!-- Powered by https://cj.rs/riss -->

and this piece of yaml will be hidden on GitHub!

Replace Asciinema Image

You can’t embed the asciinema player on GitHub for security reasons. So the asciinema documentation suggests using an image there and to link it to a webpage with the player. But on your own website, you can embed this player.

In your .md file, put:

<!-- remove -->
[![Finding the repositories with “telescope” in their name, with the README in the panel on the right](https://asciinema.org/a/427156.svg)](https://asciinema.org/a/427156)
<!-- end_remove -->
<!-- insert
<asciinema-player src="./telescope.cast" poster="npt:0:04"></asciinema-player>
end_insert -->

The output will contain only the asciinema player:

<asciinema-player src="./telescope.cast" poster="npt:0:04"></asciinema-player>

Note: you also need to add the JS/CSS files of the asciinema player somewhere in your theme. This Hugo module makes it easy.

More

See the input file (typically on GitHub) and the output of the script. You can find another real word README converted to a webpage (this gives another example of asciinema conversion using a Hugo shortcode).

With some shell scripting, you could also transform all the markdown files in your repo and put them in a subdirectory of your site, so that your project’s documentation, policy, etc… lives on your site or even on a site of its own.

Your Example!

Have you used this script to transform some markdown (or other) and insert it on your website? Open an issue if you would like a link to your use case from this README!

• telescope-repo.nvim: readme, website; features an Asciinema clip.
• neovide: readme, first iteration of their website, PR setting this up. They have now moved to mdbook and that’s great! RISS makes the first iteration of your website easy and you are free to move to more complete solutions when your project grows.
• Hugo APT Repository: readme, website, PR setting it up.

Transformations Reference

The transformations are driven by HTML comments, so that you can have different results when comments are ignored (e.g. in your GitHub README) and after executing the script on your markdown file.

Escaping

It is important that your comment starts at the beginning of the line: spaces are used for escaping, meaning that if the comment has spaces at the beginning of the line, it is ignored.

So this is escaped

    <!-- insert

but this is not

<!-- insert

Insertion

Use these two lines for text you want to have in your output, but not in the raw .md file.

<!-- insert
end_insert -->

Remove

Use these two comments for text you want to have in your raw .md file, but not in the output

<!-- remove -->
<!-- end_remove -->

Spread the Word

If you find this script useful, please consider inserting the following in your readme:

<!-- Powered by https://cj.rs/riss -->

This will help other people find the script. Thanks for spreading the word!

If you feel especially charitable, you could put this badge somewhere:

with for instance this code:

[![](https://img.shields.io/badge/powered%20by-riss-lightgrey)](https://cj.rs/riss)

Breaking API Changes

We follow semver and any change that change would cause real world READMEs to be converted differently requires a new major version. In particular, the following is a breaking change:

• adding new keywords (like remove or insert), as they may be used in the README prior to their introduction in RISS,
• changing a keywords syntax.

Benchmark

Processes 17600 lines in 10 ms

$ for i in {1..100}; do shuf README.md >>bench.md; done # Create a big md file
$ wc -l README.md
176 README.md
$ wc -l bench.md
17600 bench.md
$ hyperfine 'awk -f riss.awk README.md' 'awk -f riss.awk bench.md'

Automate with GitHub Actions

You can automatically update the markdown file in the sources of your site with GitHub Actions. Add this workflow to, for instance, .github/workflows/readme.yml:

name: Update README files

on:
  schedule:
    - cron: '30 */2 * * *'
  push:
    branches:
    - master
  # To run this workflow manually from GitHub GUI
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Check out the repo
      uses: actions/checkout@v2
    - name: Get the latest READMEs
      run: make readme-update
    - name: Commit and push if there are changes
      run: |-
        git diff
        git config --global user.email "bot@example.com"
        git config --global user.name "bot"
        git diff --quiet || (git add -u && git commit -m "Update READMEs")
        git push

and then your Makefile may contain something like:

readme-update:
	curl https://raw.githubusercontent.com/cljoly/readme-in-static-site/main/README.md | awk -f riss.awk >content/readme-in-static-site.md

Alternatively, you might configure your repositories to trigger a website rebuild when committing on your README, for instance using GitHub actions webhooks.

Contributions are Welcome!

Feel free to open an issue to discuss something or to send a PR.

See also the Spread the Word section if you would like to make more folks aware of this script.

Thanks for considering contributing! My projects all follow the guidelines outlined in this document.

TL;DR

If you just want to fix a typo or another very small thing, just create a PR.

Documentation

As the author of a tool or library, we are blind to many of the problems that users may encounter. As an external person, you have the power to spot this! Feel free to open an issue or to send a PR with proposed changes to the documentation.

Code

Pull Request

• It is advisable, but not mandatory, to create an issue to discuss the feature you want to add, so that you can make sure it has good chances to be merged. This also avoids having multiple persons working on the same thing.
  • Similarly, feel free to create a draft PR with your changes before they are completed. This is useful to point to a particular part of the code during discussions.
• Try to create one pull request per high level feature or bug fix. Then if necessary try to stage your changes by crafting multiple commits: if your commits follow a progression on your changes, it’ll be easier to review.
• New features need to be covered by adding new unit tests, where applicable. Similarly, bug fixes need to be accompanied by a regression test where applicable, to ensure that the bug does not come back. Reviewers and maintainers are in charge of enforcing this.

LLM / GenAI

• Do not use an LLM to submit PRs that you don’t understand. If you must use an LLM, rework the output yourself so that it is your work and you understand it. This also alleviate some of the concerns with copyright of material based on LLM output. Keep the PR small to make reviews easier.
• Do not use an LLM to generate issues or comments.

I Don’t Want to Use GitHub

That’s fine, feel free to send your contributions by email¹ to the address listed on the Contact page. You can also push to a publicly accessible repo and request that I pull from it.

If you are contributing this way, please use the -s/--signoff with each commit, so that a Signed-off-by trailer is added to each of your commits. Or manually add a Signed-off-by trailer at the end of your commits, like this:

Signed-off-by: Put Your Name Here <TheEmailYou@UseWith.Git>

This signifies your agreement with the DCO below.

I Don’t Know What to Do

If you don’t know what to do, but still want to help, that’s great! Look for issues labeled good-first-issue or help-wanted. You can also contact me, and tell me about your interests and skills.

Dependencies

As much as possible, I limit the number of dependencies used in my projects. Dependencies provide a short term win, by relying on someone else’s expertise and implementation to solve a particular problem. But there are two main long-term costs:

1. ongoing maintenance: spending more and more time updating an ever expanding tree of dependencies.
2. security risks: for every dependency and transitive dependency, every new version can be a malware in disguise, especially as the authors change.

Please avoid introducing new dependencies in your PRs if possible. If you do, please outline why you think it’s a worthy trade off.

Delegating Trust

In light of the XZ-backdoor and many other supply-chain attacks, I can’t give commit permissions lightly.

As a result I don’t delegate commit rights unless:

1. I’ve known someone in person for years, and
2. they have established a track-record of contributions.

It may mean that a project goes abandoned or doesn’t improve as quickly. Or that it may be overtaken by a fork that gets more attention. That’s fine. It’s the trade off I make. I would rather a fork succeed than letting a nefarious actor inherit the trust I’ve built.

Hobby Project: Take It Slow

My projects are hobby projects. They are done during my, and contributor’s, free time. It may mean that your comments or PR may go unanswered for days or weeks. I value comments, PRs and otherwise constructive interactions. It’s part of the joy of working on Open-Source software for me. But I may not have bandwidth to review some changes in a timely manner. I’m not a full-time Open-Source maintainer. At least, not yet. That’s life.

Equally, as a contributor, please feel free to say that you don’t have time or energy anymore. You can do that even in the middle of a PR. Someone else can always pick it up.

We are here to have fun developing software. We don’t owe anything² to consumers of our software. After all, our Open-Source licenses disclaim as much.

Rules

Code of Conduct

To foster a welcoming environment, we follow and enforce a code of conduct.

Meaning of “Signed-off-by” Lines in Commit Messages

When Signed-off-by trailers are used, it means that the committer agrees to the representations from the Developer Certificate of Origin (DCO), reproduced below:

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

This is the DCO used by the Linux kernel and Git projects.

When a Signed-off-by trailer is not present, we are relying on any provisions of the project’s license. In addition, if the contribution was submitted through GitHub, the GitHub Terms of Service apply, in particular Section D.6 (archived version).

Copyright Notices

In general, original copyright holders retain their copyrights. We follow these community best practices (archive):

1. If a file contains code from a third party that wasn’t submitted by that third party, then the original copyright headers are kept.
2. For code submitted to the project as a contribution, fine grained copyright ownership is tracked in the source control system (typically, Git). A simplified header is then used in the file, to convey that the work is copyrighted and licensed as a part of the project:

   Copyright XYZ and contributors.
   

   where XYZ is obviously replaced by the name of the person who leads the project.
3. Don’t change someone else’s notices without their permission.

See Also

The other Open-Source documents.

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people
• Being respectful of differing opinions, viewpoints, and experiences
• Giving and gracefully accepting constructive feedback
• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind
• Trolling, insulting or derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others’ private information, such as a physical or email address, without their explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at https://joly.pw/contact/. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla’s code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Supported Versions

Reporting a Vulnerability

First, thanks for considering reporting!

Then please contact me and describe the issue as precisely as possible. Don’t hesitate to propose a fix (for instance, with a patch sent over email) if you have one.

If you wish to send encrypted material, here are the public keys.

Signature

Commits and tags created after 2024-01-01 are signed with a key listed in this file.

The blog post gives more context and example of verification.

Disclaimer

This policy is not a guarantee that my software will have the desired behaviour or won’t cause harm. Please refer to the License of each software for the full disclaimer.

See Also

The other Open-Source documents.