search

astoff / devdocs.el

Emacs viewer for DevDocs
279 stars 16 forks source link

Navigating Devdocs buffers #39

Closed julian-hoch closed 1 month ago

julian-hoch commented 1 month ago

I like the package, but navigation in the devdocs buffer is a bit awkward, especially if you are used to use info. Would there be a chance to convert the devdocs content into info-files? That could increase their usability immensely.

astoff commented 1 month ago

What about it is awkward? Converting general HTML to info is lossy, and in particular you need give up on hyperlinks (including internal ones aka cross-references), which is really awkward.

quotuva commented 1 month ago

IIUC Info has cross-references. (Or was this not what you meant?)

astoff commented 1 month ago

Yes, but as you can see e.g. in the linked page, all cross-references in Texinfo need to be of the form "See \<node name>". So if one tried to convert your message from HTML for Info format, it would look like this, which is really awkward:

IIUC Info has see cross-references. (Or was this not what you meant?)

Therefore, the least bad way to convert your message to Info would be to strip the hyperlink:

IIUC Info has cross-references. (Or was this not what you meant?)

quotuva commented 1 month ago

all cross-references in Texinfo need to be of the form "See "

That's simply hard coded in Info-fontify-node. It would be easier to somehow get it changed; or subject it to some logic (if it's that bothersome).

astoff commented 1 month ago

I am aware of that, and that's precisely the problem. You can't decide by pure logic if a link is supposed to be part of a "see ..." phrase or not. Instead, a dedicated command in Texinfo and a dedicated markup in info file for "non-see" links would be needed. Unfortunately, Texinfo resolutely doesn't want to support general hyperlinks; you can look up the exchange I had with them in their mailing list.

So, in short, Texinfo might be a nice system to write your documentation, but you can't reasonably convert to info format random documents that were not specifically written in the Texinfo "house style". (This applies to the vast majority of non-GNU software documentation.)

Anyway, that's a tangent. If there's anything concretely awkward about devdocs.el I'd be happy to try and find a solution.

quotuva commented 1 month ago

I see. Thank you for the explanation (cf. the discussion FTR).

By 'logic' I'd merely meant some user option (which could perhaps be set file-locally) that'd turn it off entirely, without regard to the type of the link. But this is all, as you said, tangential.

julian-hoch commented 1 month ago

I just wanted to add that the awkward part seems to largely to stem from me using evil mode. It seems the devdocs package does use similar keybindings as info when using "standard" emacs, but when using evil, they are obviously not bound. So the solution would probably be to add bindings to the evil-collection package, which is a separate task and not in scope of this project. When I am a bit more experienced with Emacs and Elisp I will try to do that, for now, I can always switch to "Emacs mode" when browsing devdocs. The only thing that perhaps could be improved (and I don't know if that is possible, the source being HTML) is to populate imenu? I use that everywhere, it is quite convenient in my opinion.