[HN Gopher] Zeal is an offline documentation browser for softwar...
___________________________________________________________________
Zeal is an offline documentation browser for software developers
Author : distcs
Score : 300 points
Date : 2023-05-31 08:38 UTC (14 hours ago)
(HTM) web link (zealdocs.org)
(TXT) w3m dump (zealdocs.org)
| 29athrowaway wrote:
| Zeal is ideal when you have no connectivity. And when you want
| low latency and no distractions.
|
| Also, http://devdocs.io, which implements the same functionality
| and supports offline browsing as well.
| kachnuv_ocasek wrote:
| Wasn't a browser like this integrated in Windows at some point?
| Just download a bunch of CHM files and you're good to go to the
| wilderness.
| tuyiown wrote:
| the equivalent on macOS was to use Dictionary, but I suspect
| that it not really viable anymore due to format/rendering
| contraints: CHM probably needed IE6 like compatibility, after
| looking for docs, Dictionary needs XHTML, which might easily
| cool any enthusiasm
| destedexplan wrote:
| Or use devdocs.io on the web. It works well offline.
| AltNick wrote:
| https://devdocs.io/ absolute recommendation
| qbasic_forever wrote:
| I wish it had a proper installable app. Relying on browser
| local storage is a nightmare since your browser will randomly
| and with no warning delete it all. The whole point of offline
| docs is that they're available... offline. On more than one
| occasion I've gone back to devdocs.io and everything I saved
| locally is wiped out, and of course I'm offline and just can't
| do anything.
|
| Give me local HTML files I can stash in my filesystem. I
| actually just use wget to recursively archive entire
| documentation sites to local folders and serve them up with
| python's built in web browser. It's the only way to be sure I
| have accurate and up to date offline docs.
| denysonique wrote:
| >your browser will randomly and with no warning delete it all
|
| With Chrome based browsers this seems to happen usually on
| browser restarts after version upgrades, however With Firefox
| I have never had such issue
|
| There seems to be an Electron Desktop client:
| https://github.com/gengjiawen/electron-devdocs
| worldsayshi wrote:
| Is there no browser plugin that can give a more reliable
| offline browsing experience than browser cache and more
| convenient than wget?
| danieldk wrote:
| _Give me local HTML files I can stash in my filesystem._
|
| Apparently devdocs does have an API to download docsets. I
| just installed the Emacs package that someone recommended in
| another thread and it let me download the docs.
| clone1 wrote:
| I use this (https://github.com/astoff/devdocs.el) emacs
| package to download devdocs locally and access them from
| emacs, which is pretty great.
| 0cf8612b2e1e wrote:
| Sign me onto this same worry. It only takes one incident of
| offline mode borking to get upset.
|
| Since the devdocs representation is so standardized, I have
| wondered if I could dump their database into SQLite and
| browse it with datasette. Should even be able to maintain
| text searching.
| whitten wrote:
| Could you elaborate ? What is datasette ?
|
| Is the Zeal code open source enough that one could change
| the backend by replacing a small number of data access
| subroutines?
|
| I think all you would need to change is setter code, since
| getter code wouldn't be part of the interface. I think Zeal
| doesn't write back any data, right ?
| 0cf8612b2e1e wrote:
| Not experienced with Zeal, but I have used devdocs, which
| is open source. Devdocs parses the relevant documentation
| pages and stores them in a more structured way inside a
| browser database file. I would prefer to keep that in a
| local SQLite file I fully control. However, storing the
| data is not enough, I need an easy way to search and
| browse the documentation. Datasette is a Python project
| which spawns a web interface to a SQLite database which
| gives an interactive way to explore the data. This
| interface should be sufficient for locally hosting and
| searching the documentation.
| hirundo wrote:
| I love devdocs.io when it works, but almost every other time I
| open it, it has forgotten my documentation configuration and I
| have to start from scratch. I don't have problems losing
| cookies, etc., elsewhere. And I have a peeve with it asking me
| to reload the page over and over and over, and each time I do
| it loses my place. It's a great source otherwise.
| aosaigh wrote:
| I've tried to use an offline documentation browser a few times
| before (Dash on Mac) but have never really been able to get into
| the habit of using it. I generally just end up Googling for what
| I'm looking for. Outside of low-connectivity situations, what
| benefits do people find with these viewers?
| temp51723 wrote:
| > what benefits do people find with these viewers?
|
| I stop and think about the issue instead of just googling for
| an answer.
|
| Also, I removed the wifi card from my laptop so I can work from
| a room without ethernet letting myself get distracted by the
| internet.
| cloogshicer wrote:
| Speed and snappiness mainly. Skips at least two slow page loads
| (Google and the docs page).
|
| But yeah, it took me a while to get into the habit as well, and
| the benefit was pretty small. It mainly just feels nice.
| mindhunter wrote:
| Exceptionally quick lookups: alt + space and Dash is there with
| the search focused. I search and press alt + tab or esc to get
| back into my editor.
| eddieroger wrote:
| I have felt the same way, and curious to what others say about
| it. I assume the problem I have is that I am not always good at
| asking the questions of the documentation that I mean, and
| Google is good at inferring my meaning. More often than not, I
| don't just need the method signature, but some narrative around
| what and why. But I try things like Dash again when they come
| up, or moments like this. To your question, offline browsing is
| the biggest benefit I see. Long plane ride ahead, or cruise, or
| train ride? Take your doc with you.
| XorNot wrote:
| Honestly: that it's not Google.
|
| A more limited and focused selection of documentation gets me
| exactly what I need. It's also a lot faster then documentation
| websites.
| mxuribe wrote:
| I actually only started using Zeal during the last few
| months...but similar to you, the trap i fall into is that
| muscle memory has not been built up with me to *remember* to
| check zeal before resorting to a search engine. However, those
| few times that i *did* remember to use zeal, for me it was
| really great, solid experience!
| zomgwat wrote:
| For me, the combination of Dash and Alfred is the productivity
| boost. Alfred makes it very easy to search documentation in
| Dash. You can have unique keywords in Alfred to target specific
| packages in Dash. For example, "guava: ImmutableList" or
| "sidekiq: Client". I find it especially useful with Dash on a
| secondary monitor while the editor is on the primary so that
| both are visible at the same time.
| maleldil wrote:
| What's the difference between using Alfred to search vs using
| the hotkey to open a Dash window in search mode?
| chipotle_coyote wrote:
| I don't think there really is a significant difference,
| unless you're already using Alfred. I'm an Alfred user and
| it's kind of the "start everything place" window for me,
| the system-wide equivalent of a text editor's command
| palette, a CLI for the GUI.
| zomgwat wrote:
| Agreed. I just tried out the Dash hot key and it's
| basically the same. I'm tempted to claim the Alfred
| integration is better but that's probably just me being a
| user of Alfred.
| Linux-Fan wrote:
| For many queries, Google offers more of a "ready-made" solution
| e.g. from a StackOverflow post or blog.
|
| When looking at the offline documentation, I know that I am
| looking at a supported version (not something ancient or much
| newer than what is deployed in production) and that I am
| looking at the "authorative" answer i.e. the "real" docs not
| some third party comments.
|
| When the program I am developing is expected to run correctly
| even in the presence of errors, it makes a lot of sense to me
| to consult the authorative documentation rather than "the web"
| which rarely covers all of the possible corner cases.
| kaba0 wrote:
| Google has become a terrible search engine to the point that
| the first mention of the official documentation will be half a
| page down with some random version. I have to enter like 3
| queries for the most trivial workflow of displaying the
| official documentation's relevant pages.
|
| Also, even with high speed internet, it is several seconds at
| least, while zeal/dash will return it basically instantly.
| [deleted]
| bityard wrote:
| I have Zeal installed on my Linux desktop but I rarely use it.
|
| The reason is that most of the time, I want to read documentation
| for a specific version of whatever thing I'm using. Zeal only has
| docs for the latest version, or in some cases, major versions.
| Take Ansible and Python, for example. These tend to have breaking
| changes, new features, and hard deprecations in their minor
| version releases. So knowing that I'm looking at the docs for
| Python 3.8 vs 3.11 can be very important.
|
| One of my "someday" projects is to write a doc viewer with an
| obnoxious plethora of sources including docs shipped for every
| minor version of a program, docs for operating systems, man
| pages, info pages, maybe even wiki content for exceptional wikis
| like arch and gentoo.
| Hackbraten wrote:
| Does the Python documentation not meticulously list the entire
| history of changes at method level?
| Groxx wrote:
| I've seen this in a lot of offline/fast/??? focused
| documentation systems... and I really don't get it. Version
| matters _a lot_ to developers. Wouldn 't the developers know
| this... being developers themselves?
|
| But then I see similar things in supposedly mature and even-
| more sophisticated systems, like mypy's typeshed which only
| supports a single version of their libraries' type
| declarations.
|
| _How_? What madness leads to this? Why not support multiple
| versions, and offer a way to select them per project from
| standard dependency declarations, so you 're always reading the
| correct version?
| jnovek wrote:
| The opposite is also true: the JavaScript AWS SDK on Zeal is v2
| and the bleeding edge is v3.
| senko wrote:
| Happy user here - Zeal (and Dash on MacOS) is an easy
| productivity win, even if you're online (Django online docs
| search is notoriously bad for some reason), and indispensable if
| on a spotty connection or offline.
| maurits wrote:
| Any tips for a dash+alfred alternative on windows?
| senko wrote:
| I didn't try Zeal on Windows, but it's a supported platform,
| so I would assume you can register a hotkey there as well.
| omnicognate wrote:
| I wish this approach were more supported by those producing
| documentation. Looking things up in reference docs is one of
| those cases where reducing friction yields huge productivity
| benefits, but I still end up using a search engine (Kagi now as
| Google hides authoritative reference docs under a pile of poor-
| quality, irrelevant spam these days). I've tried Zeal multiple
| times but while the app is nice and many of the docsets are good,
| many of them _aren 't_ good: badly formatted, badly indexed,
| outdated or simply nonexistent. A search engine requires no setup
| and covers everything. It's just so horribly _slow_.
|
| If we were grown ups, all software authors/vendors would be
| providing their reference docs in a standardised form, findable,
| downloadable and displayable by a wide range of tooling,
| consistent across languages, IDEs and platforms. Zeal is the
| closest we have, and it's a noble effort, but IME it doesn't
| solve the problem well enough to be useful because there's no
| buy-in from the people producing the docs.
|
| (First to mention ChatGPT gets slapped with a wet fish. Just try
| me.)
| macjohnmcc wrote:
| I miss the documentation that was part of Microsoft MSDN
| subscription. I now work in a sandboxed environment and cannot
| access help for the APIs from within that environment so
| something that I can download in it's entirety and get into
| that environment would be ideal.
| nerdponx wrote:
| And on the other side of things, there's a growing trend in the
| Python library ecosystem of simply not writing reference
| documentation at all, instead providing either a few or a lot
| of user guides and tutorials, and directing users to either
| read those and try to interpret their mysteries, or expecting
| users to read the source code and interpret _those_ mysteries.
| It makes no sense to me. The Pydantic issue tracker for example
| is absolutely full of people simply trying to figure out how to
| use the damn thing.
| benrutter wrote:
| Yeah, I was struggling with this trend earlier when looking
| at the Textual library, which has amazing examples but
| doesn't seem to have very detailed full API documentation.
|
| I wonder why this trend is happening, especially when python
| in particular has a bunch of standards and tools to make
| generating full API docs pretty straightforward.
| nerdponx wrote:
| I think it's partly because Sphinx is clunky and people
| have been using MkDocs instead, which I believe either
| doesn't generate anything from docstrings at all, or didn't
| until recently. I don't know why they're not using Pdoc,
| maybe they don't know about it.
|
| I also get the sense that there is a growing movement among
| programmers that API reference documentation is useless, or
| not worth putting effort into, because it's possible to go
| out of sync with the code and "nobody reads that anyway".
| I've heard people say things like "if you're advanced
| enough to read reference documentation, you're better off
| just reading the source anyway." It seems to be rooted in
| some kind of combination of extreme cynicism, a distorted
| sense of how people who aren't raw beginners learn to do
| things, and of a kind of false minimalism, wherein API
| documentation is old fuddy-duddy stuff for Java and C++
| developers, and the new friendly easy way is to just read
| the examples. Such libraries also seem to exhibit a poor
| separation of public and private interfaces, so maybe it's
| just a reflection of people being bad at designing
| libraries.
| distcs wrote:
| Glad you picked on pydantic. There is no reference doc
| whatsoever. The expectation is that you are supposed to learn
| by reading examples!
|
| Back in the days of yore, software engineering teams led by
| greybeards used to be conservative in what dependencies they
| import into the projects. Those days are gone! Everyone
| imports everything today without any discerning eye.
| palata wrote:
| > Those days are gone! Everyone imports everything today
| without any discerning eye.
|
| That's even considered a feature today! If you don't have a
| language package manager that allows you to transparently
| import tons of stuff you've never heard of, then the
| language is considered crap.
| pgeorgi wrote:
| Even the good old venerable Ada language (or rather: its
| most visible vendor) jumped on that bandwagon with
| https://alire.ada.dev/ :-(
| whitten wrote:
| Does IME == In My Experience ?
| jmholla wrote:
| It does.
| omnicognate wrote:
| Yes. Apologies. I'm used to using that in chat with people
| familiar with it, but shouldn't have here. Random unexplained
| acronyms are annoying.
| bombcar wrote:
| https://www.kiwix.org/en/ Has some nice stuff for offline, but
| it's not really optimized for it.
| kaycebasques wrote:
| I'm a technical writer. I have felt this a lot myself. It is
| very comforting to know that the man pages are always there if
| I need them. Same with the Rust docs. And Beej's Guide to C
| Programming (I downloaded the PDF). Conversely, it kinda sucks
| to have to rely on a website to get info. I will kick off a
| discussion around offline docs in the technical writer
| communities that I'm part of.
| kaycebasques wrote:
| * https://technicalwriting.tools/posts/offline-docs/
|
| * https://writethedocs.slack.com/archives/C6D77HJ4F/p16855613
| 9...
|
| * https://www.reddit.com/r/technicalwriting/comments/13wvmbt
| senko wrote:
| In hope I avoid getting slapped with a wet fish, I would love
| to see a future version of Zeal with an option to ingest the
| docsets into a vector database and "chat" with it using a
| (local) LLM that's fine tuned for answering technical docs
| questions.
|
| To stay on topic, I feel the pain: Zeal is so nice I curse when
| I need to look up something in the docs that aren't supported
| (Django REST Framework, in my case), since they use a different
| doc framework and can't be easily prepared for Dash/Zeal.
| worldsayshi wrote:
| Somewhat related: wonder if using a local LLM could make it
| more feasible to federate reference documentation by
| translating various doc formats into a common one.
| TekMol wrote:
| People are not online all the time? Still manually search through
| documentation? ChatGPT, make a Haiku about this!
| Offline docs still used Death will take care of that
| soon LLMs, the new way
| slavapestov wrote:
| Some of us prefer to read primary sources written by other
| humans, instead of a hallucinatory regurgitation from a
| probabilistic token stream model.
| Rochus wrote:
| Nice. The dependency of Qt WebEngine (i.e. Chromium) is a bit
| unfortunate (size, complexity); sure
| QTextDocument/QTextLayout/QTextHtmlParser/QCssParser is not
| sufficient enough for this?
| wooptoo wrote:
| Agree, qt5-webkit takes ages to build on my machine
| Jemm wrote:
| Wish the site was clearer that Zeal serves ads.
| adhesive_wombat wrote:
| Removed in the master branch, btw.
| ta988 wrote:
| Gross
| torarnv wrote:
| I wish I could use Zeal to browse the Apple documentation as
| well, but unfortunately that's exclusive to Dash.
|
| I've even paid for Dash to get that feature, but no longer use it
| due to some UI changes in the latest version that add extra
| clicks for each search query, making the UI inefficient.
|
| Zeal seems to have be inspired by the old and efficient Dash UI,
| but I can't have both that and the Apple docs from what I can
| tell.
| whitten wrote:
| What was the feedback from the author when you told her that
| the extra clicks made it unusable ?
| torarnv wrote:
| The communication with the author (Bogdan) has unfortunately
| been lacking, taking very long to reply (months) and at best
| confirming the issues but without any plans to fix them.
|
| See https://news.ycombinator.com/item?id=25434191 for prior
| discussion about my experience.
| [deleted]
| mberning wrote:
| I still use dash 4. The newer versions removed the explorer tree
| and I don't see any way to get it back. I feel like they make
| newer, worse versions, for the sake of selling upgrade licenses.
| predakanga wrote:
| Same here - it's a shame because I'm happy to continue
| supporting the developer, but I won't pay for a functional
| downgrade.
| ta988 wrote:
| Have you tried devdocs?
| mberning wrote:
| No, not for any length of time. I prefer having a desktop
| app, and Dash 4 still works for me, so I have not had a
| reason to switch... yet.
| e12e wrote:
| Maybe I'm blind - but i can't seem to figure out a) what you get
| when you pay for Dash on Mac vs download? Or b) why i can't use
| zeal on Mac?
| larusso wrote:
| Dash is a commercial software on macOS. The author created the
| whole docset parsing/plugin stuff and markets the tool. I use
| it for years and upgraded multiple times since it's a
| timesaver.
|
| There has been controversy in the past about the tool since it
| is a glorified man page reader. The author even shared at one
| point his earnings and what he is doing with it.
|
| And no there is no zeal for macOS. I don't know the details
| behind that deal. I can only say that zeal is not as good as
| dash. The integration into macOS is way smoother than what one
| gets on windows and Linux. I tried all versions.
| Croftengea wrote:
| It's not widely advertised (probably this is the deal) but
| Zeal works fine on macOS, see this:
| https://github.com/zealdocs/zeal/wiki/Build-Instructions-
| for...
|
| You don't need to build it yourself, there is a brew formula.
| hn92726819 wrote:
| IIRC, Zeal and Dash have a deal with eachother - since Dash
| has no plans for non-mac devices, Dash told zeal the docsets
| can be used free of charge as long as zeal does not provide
| release builds on Mac. I believe you can build zeal on mac on
| your own.
| Karliss wrote:
| Here is the github discussion created by dash author
| explaining the deal
| https://github.com/zealdocs/zeal/issues/24#issue-17915169
| glintik wrote:
| Offline documentation browser for sad and unlucky developers
| without internet.
| yboris wrote:
| Looks great. Related product for comparison: _Dash_
| https://kapeli.com/dash
| warmwaffles wrote:
| I loved Dash when using a mac. But I've been full time in linux
| for the last 6 years and Zeal is the only thing _close_.
| tmarice wrote:
| If only it had Vim keybindings...
| Linux-Fan wrote:
| For me, the best documentation is often the manpages and
| perldocs, both of which can be navigated using VIM keybindings.
|
| For the remainder of documentation, I found HTML to be the
| "best" format and thus view them from the Web Browser even when
| using offline copies. To make them accessible, I use my
| browsers home page - a reduced version is shown here:
| https://masysma.net/32/ial.xhtml - and in the most recent
| version it supports some rudimentary movements like hjkl...
| [deleted]
| adhesive_wombat wrote:
| And lots and lots of third party docsets:
| https://zealusercontributions.vercel.app
| whitten wrote:
| Thank you for the link. Is there a non-zeal way of creating a
| docs to processing one ?
| arcanemachiner wrote:
| Dash, but it's a paid macOS software (which does give a free
| trial).
|
| I'd be happy to hear of others, but the situation for
| generating docs is pretty dire right now (as far as I can
| tell).
| adhesive_wombat wrote:
| It's generally a pretty manual process, as there's no
| universal mapping from upstream documentation to docsets.
|
| When you're starting with Doxygen documentation:
| https://github.com/chinmaygarde/doxygen2docset or
| https://pypi.org/project/doxytag2zealdb. If it's Sphinx-like,
| then https://github.com/hynek/doc2dash
|
| Otherwise is it probably best to look for a specific tool for
| the type of docs and then look through the GitHub submissions
| to the user-generated docset submissions for clues for
| specific code bases: https://github.com/Kapeli/Dash-User-
| Contributions/pulls?q=is...
| wzy wrote:
| I saw this post and thought there was a new update... sadly, this
| app has been sitting at the same version since I built my PC
| years ago.
| djha-skin wrote:
| A program on the bus without internet access so this is just
| perfect. I often download whole websites for this reason or bit
| better you can print pages off as PDF documents.
| ho_schi wrote:
| Zeal is great.
|
| I would appreciate it when Devhelp (Gtk) allows the user to
| install further docs. The requirement to place docs somewhere in
| "/usr/share" is obvious but doesn't fit the user needs.
| fuzztester wrote:
| The Norton Guides were good in their time, too. IIRC, Turbo C,
| 8086 assembly(?), Clipper, etc. were supported. It was a TSR too,
| so you could pop it up from any another app by a hotkey.
| TomMasz wrote:
| Zeal (portable 64-bit) runs on Wine on macOS if you don't need
| the Mac-specific stuff in Dash.
| Benlights wrote:
| What are the advantages over https://devdocs.io/ ?
| citrin_ru wrote:
| Looks similar to CHM which was my favorite documentation format
| back when I was using Windows.
| larusso wrote:
| I'm a happy user of Dash (macOS) for years now. Sadly Zeal is not
| 100% the same in terms of integration etc. at least I never got
| it running on windows and Linux like on Mac. I only use hot key
| setup (alt-space in my case) No fancy ide hot keys and such.
|
| There used to be some controversy (around 2015) when the author
| (single dev) put out yet another breaking version with new
| license upgrades. The free version was artificially slowed down.
| He added a new search backend and wanted to be compensated. So
| all users had to pay again. I upgraded 3 or 4 times. I think it's
| a great tool that solves a problem. Some feel that he only wrote
| a parser/display tool and that the price is too high. I wished I
| came up with the idea though ;)
| rjzzleep wrote:
| I didn't know zeal was being updated at all since the last
| "release" is almost 5 years old.
|
| I recently discovered devdocs.io and the emacs integration[1]
| and like it so far.
|
| [1] https://github.com/astoff/devdocs.el
| prox wrote:
| Couldn't one use Obsidian to do the same task? It sounds like
| it could.
| mananaysiempre wrote:
| The point of Zeal is downloadable docsets for offline usage
| (cppreference, MDN, GNOME docs, etc.), whereas Obsidian is
| more of a personal wiki you fill yourself AFAIU.
| nicce wrote:
| You could clone the doc repos and just open with Obsidian
| to get nice rendering.
| skrebbel wrote:
| I use cheddar for this, it's so versatile
| therealmocker wrote:
| Do you have a link? Never heard of cheddar.
| macksd wrote:
| I think skrebbel was parodying prox's reply as a
| commentary on drive-by comments about a seemingly
| orthogonal technology.
| [deleted]
| larusso wrote:
| I actually don't follow the releases just know that it is the
| variant for windows and Linux.
| Zachsa999 wrote:
| This software on Windows really is great (as of 1 year ago)
| specifically the font aliasing and size didn't match the rest of
| the system. It was way Smaller to the point of being unreadable
| for me.
| [deleted]
| formerly_proven wrote:
| Do you remember Qt Assistant? (Just slap "qt ass" in your type-
| ahead start menu!) Pepperidge farm remembers.
| mooreds wrote:
| First posted almost a decade ago:
| https://news.ycombinator.com/item?id=6171667
___________________________________________________________________
(page generated 2023-05-31 23:00 UTC)