Project

General

Profile

Bug #898

broken link in online manual

Added by Sergey Litvinov over 7 years ago. Updated almost 7 years ago.

Status:
Closed
Priority:
Low
Category:
documentation
Target version:
Affected version - extra info:
Affected version:
Difficulty:
uncategorized
Close

Description

g_x2top link is broken.
http://manual.gromacs.org/online.html

http://manual.gromacs.org/online/g_x2top.html
The requested URL /online/g_x2top.html was not found on this server.

History

#1 Updated by Justin Lemkul over 7 years ago

  • Assignee changed from Justin Lemkul to Rossen Apostolov
  • Target version set to 4.6

I'm switching this to Rossen (please hand off if someone else will take responsibility). The proper .html files are provided in the /share/html/online subdirectory of the latest version of release-4-6 but likely haven't been updated on the server. This should probably be updated upon release of the next version, anyway, with all of the new updates to documentation.

#2 Updated by Roland Schulz over 7 years ago

I suggest we let Jenkins automatically update the online manual so that we don't need to do it manual. I also suggest we have the manual (both html and pdf) online for all active branches (thus currently 4.5, 4.6, and 5.0). Further I think that we probably don't need the manual of the latest release but always the most up to date of each branch is sufficient. E.g. any changes to release-4-5 should be reflected on the website as soon as it is submitted. Because it would be improvements to the documentation which would help users of 4.5.5 not only of latest release-4-5 git version. But if someone thinks we need the latest release (4.5.5) then we could also do that with Jenkins.
Either way the easiest would be to just host both the html and pdf on Jenkins and just make a link to it from the Gromacs website. But if that is preferred we can also make Jenkins upload both to the website so it is hosted by the web-server and not Jenkins.

Comments? Is it sufficient to have latest release-4-5 or do we need 4.5.5? Can we host on Jenkins or should we copy on the web-server? Any reason not to use Jenkins and keep updating the manual manually?

#3 Updated by Justin Lemkul over 7 years ago

I don't really see a need for constant access to development PDF and HTML versions of the manual. For those interested, they can be built from source. In my mind, a manual is definitive and corresponds to a final release, which is the point at which 99.9% of users will want to refer to it. I don't know the guts of Jenkins, but if there are ways that it can be used to check the validity of the organization of our manual files, that's great, but I think it's needlessly complex to provide several concurrent development versions of documentation. After final releases are out, it would be useful to have a series of manuals available in HTML format, but not until that point, IMHO.

#4 Updated by Roland Schulz over 7 years ago

Jenkins already builds the pdf versions for all branches: http://jenkins.gromacs.org/job/Manual_Gerrit_4_5/lastSuccessfulBuild/artifact/build/gromacs.pdf , http://jenkins.gromacs.org/job/Manual_Gerrit_4_6/lastSuccessfulBuild/artifact/build/gromacs.pdf , and http://jenkins.gromacs.org/job/Manual_Gerrit_master/lastSuccessfulBuild/artifact/build/gromacs.pdf . This was very easy to set-up, I find it myself useful, and it used to detect problems during review.

I think after the 4.6 release people might want to use either the 4.5 manual or the 4.6 manual. I know quite a few people still use the last release thus I thought people might still want to still use the 4.5 manual at this point. Of course one can use the 4.6 manual for the 4.5 version, but it might be a bit confusing because it contains features not present in 4.5.

Also I think everything we can do in Jenkins is less work then doing it manually. Anything we do manually we have to do for each release and always remember to do it (e.g. updating the documentation has been forgotten before). My question is whether we currently want to have on our website the 4.5.5 manual and/or the latest release-4-5-patches manual. I personally think the latest release-4-5-patches has only advantages and 4.5.5 isn't needed, because release-4-5-patches only has improvements to the documentation (and no new features) which are also useful to any user of 4.5.5 (or 4.5.x). But if you think we should have always the manual of the latest release only/too, then I'm happy to create a Jenkins job for that too.

Uploading the HTML with Jenkins is even easier because nothing has to be build, and again the advantage is that we don't need to do it manually and remember.

#5 Updated by Mark Abraham over 7 years ago

I agree with Justin that publishing more manuals than GROMACS versions that are under official support (i.e. 4.5.5 and 4.6 whenever we release the latter) offers very limited returns. If it's easy to make them available in parallel with the official versions, and with suitable caveats near the links, then that's nice, but I wouldn't spend much time on it.

Roland Schulz wrote:

Jenkins already builds the pdf versions for all branches: http://jenkins.gromacs.org/job/Manual_Gerrit_4_5/lastSuccessfulBuild/artifact/build/gromacs.pdf , http://jenkins.gromacs.org/job/Manual_Gerrit_4_6/lastSuccessfulBuild/artifact/build/gromacs.pdf , and http://jenkins.gromacs.org/job/Manual_Gerrit_master/lastSuccessfulBuild/artifact/build/gromacs.pdf . This was very easy to set-up, I find it myself useful, and it used to detect problems during review.

Sure, that's a great tool.

I think after the 4.6 release people might want to use either the 4.5 manual or the 4.6 manual. I know quite a few people still use the last release thus I thought people might still want to still use the 4.5 manual at this point. Of course one can use the 4.6 manual for the 4.5 version, but it might be a bit confusing because it contains features not present in 4.5.

I think people should want to use the version of the manual that matches their code. We should be careful to not commit stuff to 4.6 manual that is applicable to 4.5 and vice versa.

Also I think everything we can do in Jenkins is less work then doing it manually. Anything we do manually we have to do for each release and always remember to do it (e.g. updating the documentation has been forgotten before). My question is whether we currently want to have on our website the 4.5.5 manual and/or the latest release-4-5-patches manual. I personally think the latest release-4-5-patches has only advantages and 4.5.5 isn't needed, because release-4-5-patches only has improvements to the documentation (and no new features) which are also useful to any user of 4.5.5 (or 4.5.x). But if you think we should have always the manual of the latest release only/too, then I'm happy to create a Jenkins job for that too.

After some point, we only committed bugfixes to gromacs release-4-5-patches, but IIRC the branch was around and active before that, so there might be new features there, too. Of course the manual activity is much lower. I'd just hate to see people annoyed if the documentation they read didn't match their code, or referring to pages or sections that have been renumbered in different versions.

Uploading the HTML with Jenkins is even easier because nothing has to be build, and again the advantage is that we don't need to do it manually and remember.

Even if we've been making release-4-6 documentation available via automated Jenkins builds, there's still human work on the website when we make the 4.6 release to make links and indicate definitiveness. It might be a bit less work than it used to be, though.

#6 Updated by Roland Schulz over 7 years ago

OK. If you both prefer to have always the latest release (i.e. currently 4.5.5) instead of the latest version in the release branch, then we'll just manually copy it from Jenkins to the server when we release. This will be quick.

#7 Updated by Mark Abraham almost 7 years ago

  • Status changed from New to Closed

Created #1107 to document the recurring task.

Also available in: Atom PDF