rustic-doc could be simpler and more portable

[therealpxc]

As it stands, rustic-doc is written in 3 programming languages: elisp, sh, and Lua. I believe the sh requirement is part of why Windows is not supported, right?

It seems to me like rewriting the shell and Lua components in Emacs Lisp would be a nice enhancement, and I intend to attempt making that change. I also think this would be the best way to resolve #50. But I've not written much elisp before, or used rustic-doc, so I'm feeling a bit timid about it.

So before I start that, I'd like to fix #49 so that I can use rustic-doc and get a better sense of how it works currently, and then ask for a bit of feedback in the community here.

@samhedin do you agree that this kind of change makes sense? Would you be willing to review such changes if I attempted them?

[Velnbur]

At least for Lua, I'm not sure that it's required to do anything about it. As, actually, filter.lua is only passed to pandoc to make complex filtering for it, so no additional dependencies, except, pandoc are required:

rustic/rustic-doc/Makefile

Line 4 in 3e3257e

pandoc enum.Option.html --lua-filter ../filter.lua -t native -o filterednative ;\

[therealpxc]

😳 I see! Okay, that makes sense. I think indeed that the only thing I really want to change here is the shell script stuff.

[samhedin]

Hey!
It's fun to see someone use rustic-doc and make issues for it. As someone said, the lua is a filter for pandoc so it's hard to make into elisp. The filter used to be written in Haskell but people complained so I rewrote it in lua, with way worse results (I'm even worse at Lua than I am at Haskell).
I agree that the shell script is a good candidate for elisp. Right now, it's too long to be a shell script anyway and elisp ought to be a good candidate.

TBH the entirety of rustic-doc is kind of half baked. I spent some time on it when I was on summer break during school as a way to start learning elisp, but shortly thereafter I stopped writing rust and haven't written it since, so I never had the chance to test, or motivation to further develop it.

One of the biggest potential improvements is that the rust community have at some point discussed that documentation should be exportable to json. I don't know the status of that but that would allow rustic-doc to get rid of the pandoc dependency, and the accompanying lua... And probably end up formatted better.
There are some other programs that may be a better starting point: https://www.reddit.com/r/rust/comments/hx16j0/rustyman_a_commandline_viewer_for_rustdoc/
https://github.com/sminez/roc

Regarding reviews I'm happy to assist to the extent that I can. My biggest obstacles are that I don't write Rust so I can't really test anything properly, and I don't have much spare time, as I made the tactically unsound decision of having two kids.

[Velnbur]

I found the issue: rust-lang/rust#76578

[Velnbur]

Due to rust-lang/rust#128963 rustdoc has an option --output-format=json, but my version (1.79.0) requires -Z unstable-options with nightly toolchain

[Velnbur]

There is a crate called rustdoc_json, which, as I understood, let's user in build.rs automaticly override toolchain using rustup and generate documentation in JSON, but still this seems to me complicated to use, as it at least it would require compile or fetch additional binary