search

keith / xcode-man-pages

A HTML export of Xcode's man pages
https://keith.github.io/xcode-man-pages
53 stars 5 forks source link

Versioned URLs #1

Open stefanschmidt opened 2 years ago

stefanschmidt commented 2 years ago

Currently the man pages are served without any versioning in the URL. e.g. https://keith.github.io/xcode-man-pages/ls.1.html

Somebody might write about something specific to the currently served Xcode version and link to a man page. When a new version of the man pages is published on the website the link then points to the new version instead of the one that the link originally pointed to.

Or somebody might be implementing a program and wants to casually check for compatibility of a command line option or type signature across macOS versions (possibly using diffing tools on earlier repository revisions as a systematic next step).

Thus it seems meaningful both for link stability and researching to have versioned URLs. The most straightforward approach might be to include the Xcode version or the build number in the URL. e.g. https://keith.github.io/xcode-man-pages/13.3/ls.1.html or https://keith.github.io/xcode-man-pages/13E113/ls.1.html

Another approach might be to serve the last available Xcode release for a macOS version and include the macOS version in the URL. I'm not sure though if that actually would be meaningful. e.g. https://keith.github.io/xcode-man-pages/macOS12/ls.1.html

For simplicity and brevity it might be good to keep the current URL naming convention and just provide the versioned URLs as additional access method. Talking about brevity, if the project turns out to be popular, it might be worth considering moving it to a shorter domain (something along the lines of xcman.io/ls.1 for the latest Xcode release).

Anyway, thanks for offering this usable, readable and up-to-date website!

keith commented 2 years ago

Yea good point! this would be nice to do. At least in the short term you can also jump back in the git history pretty easily. https://github.com/keith/xcode-man-pages/blob/29e80156073bfe5ee182381383d62d4ee9a014c4/docs/ld.1.html

mrienstra commented 1 year ago

Came here to say the same thing! In the absence of the website supporting this, would be nice to tag commits or make releases, to make it a little easier to navigate / improve URLs.

I'd be down to help with this, it seems like it could be pretty straightforward (famous last words). I'd love to hear your thoughts on what an acceptable solution would look like.

keith commented 1 year ago

ah yea tagging commits with the version they're generated from is a good idea too.

I haven't really thought about it but I'm happy with any of the versions that throws stuff into a subdirectory. I think it would have to be based on the Xcode build number as that's the only thing that's unique enough (i think to make it more clear we'd want to do the full build version like what I include in the commit messages like 14.3.14E5197f).

As long as we maintain some nice way to diff I think we're good. Maybe that would be that we keep doing what we're doing in the 1 primary directory, but then also cp -R those to the versioned directory