Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: various updates and text fixes in HTML for MD conversion #4837

Merged
merged 47 commits into from
Dec 17, 2024

Conversation

neteler
Copy link
Member

@neteler neteler commented Dec 14, 2024

This PR contains various HTML updates and textual fixes in preparation for the planned markdown conversion (see also #4748).

For this PR, I have (briefly) reviewed all ~600 GRASS GIS manual pages by converting them to MD for a quality check, and then updated the original HTML files accordingly. Thus it is also a backport candidate for G84.

Changes in detail:

  • adding missing intro sentences
  • added module name in the first sentence where missing
  • http -> https
  • selected URL updates for broken URLs
  • selected additions in "SEE ALSO" sections
  • fix suboptimal HTML formatting (flags, special names, ...)
  • add missing keywords on metapages
  • remove leftover Last changed: $Date$ entries from CVS/SVN days
  • simplify selected -<dl><dt>... to <ul><li>... for improved MD conversion
  • replaced <tt>...</tt> with <code>...</code>

For an easier review, the changes have been submitted in separate commits:

Extra changes:

  • replaced <tt>...</tt> with <code>...</code> in 14841b2
  • dot product: replaced . with &middot; f8ea200
  • review by @echoix: 1645685 and 6fd0a66
  • utils/g.html2man/htmltags.txt: dropped outdated file (see instead utils/g.html2man/ggroff.py) in 92597b2

This PR contains various updates and textual fixes (incl. adding missing intro sentences) in preparation of the planned markdown conversion (see also OSGeo#4748).

For an easier review, the changes have been submitted in separate commits:

- [ ] **db**:
- [ ] **display**:
- [ ] **doc**:
- [ ] **general**:
- [ ] **gui**:
- [ ] **imagery**:
- [ ] **lib**:
- [ ] **misc**:
- [ ] **raster**:
- [ ] **raster3d**:
- [ ] **scripts**:
- [ ] **temporal**:
- [ ] **vector**:
- [ ] **visualization**:
@neteler neteler added manual Documentation related issues HTML Related code is in HTML docs backport to 8.4 PR needs to be backported to release branch 8.4 labels Dec 14, 2024
@neteler neteler added this to the 8.5.0 milestone Dec 14, 2024
@neteler neteler requested a review from wenzeslaus December 14, 2024 13:28
@neteler neteler self-assigned this Dec 14, 2024
@github-actions github-actions bot added vector Related to vector data processing libraries labels Dec 14, 2024
@github-actions github-actions bot added GUI wxGUI related raster Related to raster data processing temporal Related to temporal data processing Python Related code is in Python database Related to database management labels Dec 14, 2024
@github-actions github-actions bot added macOS macOS specific C Related code is in C labels Dec 15, 2024
@echoix
Copy link
Member

echoix commented Dec 15, 2024

Ok, I'm getting bored, but didn't finish going through all lychee detections/false positives

I ran:

./lychee . --suggest --require-https --archive wayback --base file:///home/vscode/grass/dist.x86_64-pc-linux-gnu/docs/html/ --output lychee_output.md --cache --i
nclude-fragments --include-verbatim --format markdown --cache-exclude-status '429, 500..502'

The output of what I was working on:
lychee_output3.md

The same output after I worked on:
lychee_output4.md

The cache file, two versions in case it is useful (list of links):
lycheecache.zip

A dump of links, created with

./lychee . --suggest --require-https --archive wayback  --include-fragments  --dump --output lychee_dump.txt  --mode plain

lychee_dump.txt

In case someone would want to reproduce the same commands with cache, I added (temporarily) these lines in the .gitignore so the cache/result files wouldn't have their links extracted too:

.lycheecache
lychee
lychee-x86_64-unknown-linux-musl.tar.gz
lychee_output.md
lychee_output

@neteler
Copy link
Member Author

neteler commented Dec 16, 2024

g.setproj doesn't seem to be built/available online in 8.4 and 8.5, and also 7.8, 7.0. It exists for 6.4 and 6.5 https://grass.osgeo.org/grass64/manuals/g.setproj.html

Google search for "grass g.setproj" links to 6.5

Right: g.setproj is essentially unneeded code as g.proj has taken over (many years ago it was discussed in the grass-dev list to keep it for easier lookup of code-chunks but I'd suggest to rather remove it in a separate PR). I see a few mentions in messages like d.*, g.region and wxGUI wizard, though (to be updated as well then).

@neteler
Copy link
Member Author

neteler commented Dec 16, 2024

What is the correct URL for "Internet: http://grass.osgeo.org/home/contact-us/" in https://github.com/neteler/grass/blob/0be2b97149407d76add9346d207ff52eb205a530/doc/development/rfc/legal_aspects_of_code_contributions.md#L69? It is dead, http, and I don't seem to find the equivalent. (It is not a html file, but it appeared in the search for http only links).

The closest page seems to be https://grass.osgeo.org/about/team/ - what do you think, @veroandreo ?

@veroandreo
Copy link
Contributor

What is the correct URL for "Internet: http://grass.osgeo.org/home/contact-us/" in https://github.com/neteler/grass/blob/0be2b97149407d76add9346d207ff52eb205a530/doc/development/rfc/legal_aspects_of_code_contributions.md#L69? It is dead, http, and I don't seem to find the equivalent. (It is not a html file, but it appeared in the search for http only links).

The closest page seems to be https://grass.osgeo.org/about/team/ - what do you think, @veroandreo ?

There is no contact info on the team page. Why not either https://grass.osgeo.org/support/community/ or Discourse directly?

@neteler
Copy link
Member Author

neteler commented Dec 17, 2024

The closest page seems to be https://grass.osgeo.org/about/team/ - what do you think, @veroandreo ?

There is no contact info on the team page. Why not either https://grass.osgeo.org/support/community/ or Discourse directly?

Okay, updated in a9938d7

@github-actions github-actions bot added the RFC Request For Comment (RFC) document label Dec 17, 2024
@neteler
Copy link
Member Author

neteler commented Dec 17, 2024

Seems we are ready to go?

Copy link
Member

@echoix echoix left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since what could be remaining is fine tuning dead links with archives, and that would be a never ending endeavour, I think that what needed to be fixed in here is fixed, and it improves on the previous state.

So yes, I think this should go as is

@neteler neteler merged commit ab90c5e into OSGeo:main Dec 17, 2024
27 checks passed
@neteler neteler deleted the manual_prepare_for_MD_conversion branch December 17, 2024 19:17
neteler added a commit that referenced this pull request Dec 17, 2024
…ort of #4837)

This PR contains various HTML updates and textual fixes in preparation for the planned markdown conversion (see also #4748).

For this PR, I have (briefly) reviewed all ~600 GRASS GIS manual pages by converting them to MD for a quality check, and then updated the original HTML files accordingly. Thus it is also a backport candidate for G84.

Changes in detail:

- adding missing intro sentences
- added module name in the first sentence where missing
- http -> https
- selected URL updates for broken URLs
- selected additions in "SEE ALSO" sections
- fix suboptimal HTML formatting (flags, special names, ...)
- add missing keywords on metapages
- remove leftover `Last changed: $Date$` entries from CVS/SVN days
- simplify selected `-<dl><dt>...` to `<ul><li>...` for improved MD conversion
- replaced `<tt>...</tt>` with `<code>...</code>`

For an easier review, the changes have been submitted in separate commits:

- [x] **db**: 473b95b
- [x] **display**: fca42da
- [x] **doc**: e473bc8
- [x] **general**: 00930f5
- [x] **gui**: e9259cf
- [x] **imagery**: e700a7c, c888dba
- [x] **lib**: 6da27ca
- [x] **misc**: bfa7c0d
- [x] **raster**: 0c5ca83
- [x] **raster3d**: 0c44c95
- [x] **scripts**: e5bd683, 7b70b03
- [x] **temporal**: a173a8f
- [x] **vector**: b5167fa
- [x] **visualization**: 81e9756

Extra changes:
- [x] replaced `<tt>...</tt>` with `<code>...</code>` in 14841b2
- [x] dot product: replaced `.` with `&middot;` f8ea200
- [x] review by @echoix: 1645685 and 6fd0a66
- [x] `utils/g.html2man/htmltags.txt`: dropped outdated file (see instead `utils/g.html2man/ggroff.py`) in 92597b2

Co-authored-by: Edouard Choinière <27212526+echoix@users.noreply.github.com>
@neteler neteler modified the milestones: 8.5.0, 8.4.1 Dec 17, 2024
@neteler neteler removed the backport to 8.4 PR needs to be backported to release branch 8.4 label Dec 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C Related code is in C database Related to database management display docs general GUI wxGUI related HTML Related code is in HTML imagery libraries macOS macOS specific manual Documentation related issues misc module Python Related code is in Python raster Related to raster data processing raster3d RFC Request For Comment (RFC) document temporal Related to temporal data processing tests Related to Test Suite vector Related to vector data processing
Projects
Development

Successfully merging this pull request may close these issues.

3 participants