Hacker News new | past | comments | ask | show | jobs | submit login

Yeah the way I think of this is that some people write a text or Markdown file with shell commands for documentation.

I INVERT this, and write a shell script with comments :) That way someone else can reuse your knowledge more easily (and your future self as well).

Examples:

Constructing a big curl command to use the Zulip API, and also using jq for the first time. I used this to easily make a blog post out of a long Zulip thread [1]

https://github.com/oilshell/oil/blob/master/services/zulip.s... (oops some tabs snuck in here)

Figuring out how to use uftrace (and successfully optimizing Oil with it [2]):

https://github.com/oilshell/oil/blob/master/benchmarks/uftra...

Though one issue is that shell scripts don't really specify their environment, but there is a large number of tools growing around containers that can solve this problem. (Basically Docker is being refactored into something more sane; thank you to OCI and others.)

So I hope to integrate the Oil shell and containers more so shell scripts are more reproducible. I mean most of the container tools are already command line tools so in some sense it's already done, but you can imagine closer integration (e.g. not just passing code as text from outside the container to inside the container).

----

I wrote some notes about the documentation issue here: http://www.oilshell.org/blog/2020/02/good-parts-sketch.html#...

And one thing I've wondered is if Oil should literally run shell out of markdown, so you can create executable docs. I can see it being useful, but it might be something you should do with a separate tool that converts markdown code blocks to a shell script...

[1] http://www.oilshell.org/blog/2020/11/more-syntax.html

[2] http://www.oilshell.org/blog/2020/01/parser-benchmarks.html




I also do this with my personal scripts; I just use comments for commands and parameters I'm not using frequently, and then I can just grep the script folder and/or use an older script as example.

Writing that knowledge in some document is nice but in reality it's just more effort for no real gain, especially as it only helps if the relevant note can be found quicker than an online example/explanation.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: