The LAMMPS developers are thinking about dropping the PDF format version of the LAMMPS manual. This would allow us to focus on the HTML version, use HTML-only features, and skip checking if the documentation source files, especially the embedded mathematical expressions, are compatible with LaTeX output.
Please let us know how you feel about this change by stating your choice in the poll below.
- I agree with removing support for the PDF version of the LAMMPS manual
- I disagree with removing support for the PDF version of the LAMMPS manual
As an alternative, you can send an email to [email protected] stating whether you agree or disagree with removing support for the PDF format version of the manual and optionally provide arguments for your preference.
I can’t provide exact figures, but I think we would all agree that searching a PDF is more energy-efficient than querying Google servers. That’s my 2 cents.
The html lammps doc can also be built and searched locally.
When using the search engine there, is makes local research as far as I can tell.
While I am not questioning that statement, here are a few things to consider:
- Our Google search box is using less energy than the default Google search since it does not contain the “AI Summary”.
- The amount of energy saved by searching the PDF is tiny compared to the amount of energy we use for running simulations.
- Also, if you look at how many people use ChatGPT or Perplexity.ai or other similar AI based tools and how much they use it, the savings are also symbolic.
- By making the HTML documentation more appealing there is the potential that people will pay more attention to it and thus avoid running simulations with bad settings (I know, hope always dies last)
BTW: if people here want save energy for their regular web searches with Google, they can add a custom web engine with the URL https://www.google.com/search?q=%s&udm=14 in their web browser and transport themselves back to the time before AI clogged up things.
P.S.: I found this hack here: OpenWebSearch – a European index for European search engines • The Register and here https://udm14.com/
2 Likes
Sorry, but no. We replaced that. Normally, Sphinx websites include some JavaScript search code for the search box, but we dropped this a long time ago since it was blowing up the patch files.
Since we don’t distribute patch files anymore, we could look into restoring that functionality.
Although I vaguely remember that the quality of the JavaScript search is somewhat limited.
My mistake. I was too quick and only looked to the local search page generated, not at the addresses. They indeed point to the docs.lammps.org page.
Sure, the energy argument is weak compared to streaming platforms too. It’s just that I find it practical to have a compiled manual in the form of a single file, which I can search locally.
I wish I had the time to work on restructuring the user manual, as discussed a few years ago in How to improve communication between LAMMPS users, how to better support LAMMPS?
I don’t even remember when was the last time I used the PDF version of the manual.
We’ve been chipping away at it slowly but steady. Often, when I have the feeling that I am explaining the same thing too many times, I update the corresponding part of the manual.
Also the error messages have been improved quite a bit over the last months.
Once the next stable release starts percolating through the various systems for installing LAMMPS without compiling, confused users will see a URL with many error messages pointing them to additional explanations.
Well, in my case, it is part of my work (hence I am abstaining from the vote). I was expecting that somebody would say that the PDF version looks better and therefore preferred (LaTeX typesetting is generally more pleasant to the eye than what HTML provides).
Yes, the manual has been greatly improved. I still find it confusing that the keywords’ documentation is scattered across the command description without an index that can be clicked from the syntax box.
That hierarchical index is very handy for browsing both the HTML and PDF versions of the manual.
PS @akohlmey: yes, LaTeX has always looked better. It will always do.
As it happens, I was discussing something similar with @sjplimp yesterday. Due to its size, large parts of the documentation still resemble the (limited) markup of the custom txt2html tool (which is still used for www.lammps.org and the reason it has a strong 1990s vibe) from which most was auto-converted and then gradually make consistent. To come up and implement a new layout (= similar content but “native” RST style markup) is going to be a herculean task.
2 Likes
BTW: we’ve recently put together a write-up summarizing many of the things that have happened to LAMMPS over the last years (or rather decades?): [2505.06877] LAMMPS: A Case Study For Applying Modern Software Engineering to an Established Research Software Package
2 Likes
Unfortunately such a restructuring of the documentation requires substantial editorial work, which I doubt could be outsourced to automated agents. The idea of establishing a non-profit organisation (with enough funding) could be a way to tackle the problem.
Thanks for sharing your perspective. It is a perfect summer reading 
For what it’s worth here are my 2cts concerning the use of the documentation in the last year.
I’ve mostly used it in two cases:
- Looking for something myself
- Using it as a reference to explain LAMMPS to someone (intern, colleague or even here).
For the first case, when I have a terminal and no web browser opened, I often look at the source files. When you know the naming convention of the files, which is dead simple, and where to look, finding the file you’re looking for in Vim is very fast. (I even think Aidan is faster than me at this game with Emacs.) This looks very much like using a text-based web browser to look on the web version of the manual.
When I explain things to people, it often refer to particular concepts and the html version has two advantages compared to the pdf:
- There is one page per topic/command.
- You can bookmark pages in web browser and have more than one open at the same time.
Even if I recognize all the effort put in the pdf version, its 3k and something pages make it hard to use in the context I’ve been working lately. With students, I tend to go to what they need and I don’t want them to be discourage by the size of the documentation. With colleagues, most of the time we focus on details and it is often convenient to have a page you can scroll up and down top to bottom without loosing the content, and tabs containing the other stuff we are discussing about. This is not the case with the pdf version where commands can be several page long and changes from one to the other can happen in the middle of a page.
Even if I agree with the elegance of the LaTeX output, in which I think I remember some work has been put in the recent time, I hardly see it competing against the html and raw files in term of ease of navigation. But if there are some situations in which people prefer to use it, fair enough, it might deserve some attention and upgrade.
Latex equations rendered in sphinx html look pretty good to me
Also responsive html is more flexible to various device screens than portait us letter