Fix all remaining style issues, and many other issues

[ifokkema]

Fix all remaining style issues, and many other issues

For this commit, I have reviewed every single page of the documentation. The intent was to fix all remaining style issues (mostly applying formatting and fixing broken lists), but since I was going through all the pages for this, it would be incredibly inefficient not to fix other issues that I encountered right away. I'm sure the diff will be unreadable, so I hope this PR will provide sufficient information to be able to review these changes.

Style issues

• Most commonly, the lists were affected (e.g., the example list on every variant type page). Nested lists were not formatted as lists, boldface applied on the original page was missing, variant descriptions weren't escaped, which resulted in parts of them being interpreted as styling (underscores, asterisks), line breaks as applied in the original design were missing, etc.
• Considering line breaks; Markdown can insert a break by appending two spaces to the last line, but the linter doesn't like that. As such, I used <br>, instead.
• Considering the styling of variant descriptions, the following rules were applied:
  • Standard variant descriptions were surrounded by backticks: `c.100A>G`.
  • Variant descriptions that can never be correct (e.g., "do not use ..." examples such as delA variants or IVS2+2del examples) where annotated as <code class="invalid">...</code>. This highlights the variant descriptions in red, reminding the user never to use them.
  • Variant descriptions that were incorrect because of the specific sequence context (e.g., the 3' forwarding rule wasn't applied) were styled as "normal" variants, using backticks. I did this to prevent users "scanning" the page to get the idea that these variant descriptions (like c.100del or so) are always wrong.
  • Variant descriptions with highlighted sequence were highlighted with tags like <code class="ins">...</code>, <code class="del">...</code>, etc. Because variant descriptions are currently styled to be a bit smaller than the original text, nesting these (`c.100A>G<code class="spot1">(;)</code>110G>C`) got really ugly. Decided to not nest them, and use `c.100A>G`<code class="spot1">(;)</code>`110G>C`, instead.
  • The backtics do not always stop Markdown from interpreting _ and * as styling. I don't see the pattern when it works and when it doesn't, so I just escaped everything in variants that were styled by Markdown using their internal syntax.
• Gene symbols were formatted to be in italics.
• Code style rather than styling on the page: the documentation source code consists of very, very long lines. Each paragraph was basically one line. That makes it hard to review the code, but also, diffs in git would show enormous amounts of text, and merge conflicts are more likely to happen. I decided to put all sentences on a new line in the source code. This works better than simple hard-wrapping because the addition of a sentence would only cause a simple insertion using the "new sentence, new line" method, whereas lots of lines in the code would be affected using simple hard-wrapping. I stopped there and didn't continue hard-wrapping all the lines, but if we have a consensus here, we could still do that in the future.
• Some pages didn't show the discussion section well. It was a long list instead of note boxes.
• Improved the styling of the SVD-WG### pages. The header is now styled and makes the status of the proposal quickly recognizable.
• I took the liberty to style the list of past HVNC members on the HVNC page. Having one long list at 2013-2021 didn't seem nice; I made it into a sublist. Also, put the names first, and their roles after their names (as it was done in the list of current members).

Other issues

• The pages were chockfull of typos. These were all fixed, also using spellcheck software.
• Also, commas were frequently left out. I added them where needed, but this will not be perfect. I may have overdone it somewhere or forgot to add commas elsewhere, but I do feel the end result is a lot more readable than the original.
• Some typos were introduced due to automated processing. E.g., underscores had been replaced by asterisks to change _this_ into *this*, but in some places, it had changed, e.g., NC_000001.10 into NC*000001.10.
• Several links pointing to HGVS.org were fixed. There are more links to files there, files that we don't have in the new repo. We should discuss whether we want to bring those over to our repo, or leave them at HGVS.org.
• Fixed some links on the Checklist page. The links claimed to link to general recommendations, but linked to the "Basics" page, instead. Renamed the links and gave the links proper hashes to link to the correct part of the page.
• Some pages we don't have, e.g., an index page for "Recommendations". Removed links to pages like these.
• Fixed dates on several pages, where years were left out. Had to look up what year they were referring to, and fixed all dates.
• Removed a registration link that is no longer relevant.

Changes to the content

• Some wording on a very small number of pages was changed to fix "weird" and unclear sentences, but the meaning of the sentences was always left as-is.
• Several pages still mentioned conversions as valid variant types. This was removed.
• The DNA / repeated page contained a duplicated block with small differences in the content. Resolved this the best way I could. The page itself is a mess, and I'm sure the content is anyway incorrect, and should be revised.
• Variant descriptions sometimes also contained mistakes. E.g., the fix also reported in #137 had already been fixed in this branch when that issue was created. I only fixed variant descriptions where it was completely obvious that the error was a typo. Other problems were reported instead or written down to discuss later.
• In the DNA / complex page changed (603) to N[603], as the former is invalid.
• Remove "indel" except for where it's made clear it shouldn't be used.
• The RNA / deletion and RNA / duplication pages described it was allowed to add a sequence at the end of the variant description. Removed this, and instead, the recommendation not to do this was copied from the respective DNA pages.
• Synchronized several sentences between DNA and RNA pages (mostly warnings about what or what not to do). Also synchronized notes between pages. Sometimes, the same notes were on several pages, but they had small differences.
• Modified an example on the RNA / delins page; removed the suggestion that two nearby variants don't have to be merged when one of them is a frequent polymorphism. I felt confident removing this as this had already been done on the DNA/delins page, but I did leave one other such recommendation in. It should likely be removed as well, but I will only do this after consultation with the HVNC.
• Fixed a p. example to r. on the RNA / allele page.
• Fixed DNA examples to RNA on the RNA / repeated page.
• On the RNA / splicing page, fixed a confusing mistake in an example text and removed all LRG-based "alternative descriptions". They served no purpose but only repeated the same descriptions with an LRG reference sequence. Since these are no longer made, the use of these "alternative descriptions" was only confusing. Also, other pages don't list alternative descriptions using other reference sequences.
• Fixed some examples on the Uncertain page. Not all of these issues have been fixed. Some examples: The section on deletions had confusing text about insertion variants. Removed everything mentioning insertions, and where needed, moved this to the part about insertions. When already explained in the insertions part, simply removed the duplicated text. Several examples claimed they were described on hg38, but they were described on hg19. Added r.0?, r.(=), and p.0?. The 0? variants are mentioned in the text on different pages, but never fully explained and therefore, deserved a spot here. The r.(=) variant is duplicated from the p.(=) example already given on that page.
• Two changes were made to the contents of the background / basics page. The Google group was added as the preferred method for contact. We still mention the email address, but it is no longer the only method for contacting us. Some additional reasons for using the Google group were given as well. Secondly, the term "allelic variant" was removed from the list of terms that we use as an alternative to "mutation", as we never use "allelic variant" anywhere on the website.
• On some pages, we were named the "HGVS standard". Replaced this with "HGVS nomenclature".
• Restyled the amino acid translation table on the standards page, made it look like it was on the original page. It is easier like this to look up an amino acid.
• The background / numbering page had lots of vague sentences. Some were fixed / clarified, but there are still a few sentences that I don't understand or really don't like. We'll have to look at that later. Also, changed "pathogenic variants", a term that the documentation argues should not be used, to "clinically relevant variants".
• The background / refseq page had some conflicting information about transcripts to be selected for variant reporting. It was said MANE select transcripts should be used, but further down, information was given that the longest major transcript should be used. Moved that part up and added that this was the alternative solution for non-human organisms. Also removed a part on how EBI selects which transcript to use, as this was related to pre-MANE transcript selection.
• On the background / glossary page, changed several confusing mentions of "HGVS-DNA" to "HGVS (DNA)", "HGVS (DNA, RNA)", or "HGVS (DNA, RNA, protein)", depending on the molecule types on which this variant type can exist.

[ifokkema]

Wow. This was an enormous amount of work @ifokkema . Thank you.

You're welcome!

It's too late now, but in the future I would very much appreciate smaller PRs with tighter focus. I would especially appreciate separating reformatting (without content changes) from other kinds of changes. However, I also know from personal experience with this site that it's very hard to resist the temptation (and sometimes the necessity) to fix multiple areas at the same time.

The main issue was actually time - fixing styling, typos, and mistakes in variant descriptions separately would require me to run over all pages three times. I estimate to already have taken about 50 hours for this work; separating all of this would have meant re-reading everything several times, comparing the new with the old pages multiple times, etc. And, of course, it would duplicate work as sometimes mistakes in variant descriptions were fixed by styling them. I anticipated this, which is why I suggested earlier to split my work into "functional" parts (DNA pages, RNA pages, protein pages, etc). But I fear that, nonetheless, each PR would have been very difficult to review fully.

In any case, I am very certain that you've substantially improved the consistency of the site. Again, thanks!

I certainly hope so! :smile: