This looks awesome, but how do I use it?

[dabrahams]

This project looks extremely promising to me; I'm so excited!

But I'm not fluent in the idioms of go, so it's not obvious how to build, install, and invoke it. Just a little help in the readme for users of other languages would make a big difference.

Here's my intro experience:

• Couldn't figure out how to make go get do anything
• so I read the go help build output
• I checked out the project and did go build -o ~/bin/lmt, which left an executable in ~/bin. Great.
• lmt --help seemed to be trying to open --help as a file
• So I made a simple test file (test.txt)
• But then lmt test.txt had no effect.
• Removed main.go and lmt *.md in the source dir to make sure it worked; it seemed to, but it generated different contents for main.go, which didn't actually compile.
• Eventually figured out it doesn't support ​```c++ blocks
• After lots of trial and error, figured out that you need to lmt README.md WhitespacePreservation.md SubdirectoryFiles.md LineNumbers.md, in that order, to reproduce main.go

[dabrahams]

...and now I see there's a note about invocation at the very bottom of the README; if I've taken the trouble to read through the whole implementation I might find it. Would you be open to a PR that fixes this?

[driusan]

Thanks for the feedback! It might be worth re-factoring the way the "code" is structured in the repo to have a more traditional README with usage instructions, and start the implementation in a different file, rather than diving straight into implementation.

But the summary of usage is: run lmt with a list of markdown files as arguments. There are no options. Markdown code blocks are either named by having a double quote enclosed string after the markdown language tag of the code block, or filenames by having a non-quoted filename (where filename is defined as "meets the regex in the README"). If any code block has a <<< ... >>> enclosed line, it's replaced by the last code block with that name in any files passed as arguments (in the order they were passed on the command line). You can use this to start with a naïve implementation of something then progressively overwrite it as your thought process/narrative/implementation evolves.

For installing, go get github.com/driusan/lmt should be enough to install it in the $GOBIN directory (or at least, that was the case when it was initially written.. I'm not sure if Go automatically installing things has changed since go modules were added.) The go code is extracted alongside the markdown in the README for bootstrapping purposes. The lmt command in the README should just need is just if you've changed the code of lmt itself.

I just had a look at your test file and it looks good, it looks like there's a bug in a regex in lmt where it's getting confused by the + in the language name and parsing things incorrectly. It works for me if I change the language of the codeblocks from "c++" to "cpp" in your test file. lmt itself doesn't do anything language specific other than add line number pragmas if it knows the language. (which means your PR should add C style lineno pragmas for C++, but won't fix the bug with the regex.. I'll try and have a look into fixing the bug..)

[dabrahams]

Need to read your comment, but I created this which I thought you might find useful as a getting started guide:

https://gist.github.com/dabrahams/d8d44126a6472e5c3308ffa778c55ddd

[driusan]

I just pushed a commit which should fix the regex so that "c++" passes the part of the regex used for recognizing the language, it should work with c++ code blocks now.

[dabrahams]

Ah, well thanks, but I think I was just wrong to use "c++"; as the list I referenced shows, it's "cpp". Point is, using that will not produce the intended syntax highlighting anywhere. On the bright side, you may now have written the only tool in the world that recognizes ```c++... blocks ;-).

Thanks for the feedback! It might be worth re-factoring the way the "code" is structured in the repo to have a more traditional README with usage instructions, and start the implementation in a different file, rather than diving straight into implementation.

I think that would have been easier for me, yes.

But the summary of usage is: run lmt with a list of markdown files as arguments. Markdown code blocks are either named by having a double quote enclosed string after the markdown language tag of the code block, or filenames by having a non-quoted filename (where filename is defined as "meets the regex in the README"). If any code block has a <<< ... >>> enclosed line, it's replaced by the last code block with that name in any files passed as arguments. You can use this to start with a naïve implementation of something then progressively overwrite it as your thought process/narrative/implementation evolves.

That's great!

For installing, go get github.com/driusan/lmt should be enough to install it in the $GOBIN directory (or at least, that was the case when it was initially written.. I'm not sure if Go automatically installing things has changed since go modules were added.) The go code is extracted alongside the markdown in the README for bootstrapping purposes. The lmt command in the README should just need is just if you've changed the code of lmt itself.

Yeah, see, I don't have a $GOBIN variable set in my shell and can't figure out what that might be (I installed go using homebrew).

…

On Fri, Feb 19, 2021 at 5:11 PM Dave MacFarlane ***@***.***> wrote: I just pushed a commit which should fix the regex so that "c++" passes the part of the regex used for recognizing the language, it should work with c++ code blocks now. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#10 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAKYIK4BPP7WAOGNMUQ6ILS74D4PANCNFSM4X5CWGBA> .

-- -Dave

[dabrahams]

Latest updates to https://gist.github.com/dabrahams/d8d44126a6472e5c3308ffa778c55ddd might make a good foundation for a new README, if you make it less language-centric. Cheers!

[driusan]

I reread the existing README and your gist and I think you're right, your version is much better and more user-friendly than diving into the implementation. (I also noticed the existing implementation could use some editing... I don't know if I've really read it since I wrote it and got it working.)

Could you send a PR that:

1. Moves README.md to Implementation.md
2. Adds your gist as-is as a new README.md?

I'll still modify your content before merging and it might take me a while before I get a chance, but that way the authorship information in the git history will be correct.

[enderger]

To add my own input, I’d say that a few usage and error messages would go a long way. Invoking it without arguments should probably print a help message, I'll see about adding that in a PR.