Update all Books to point to Project Wiki instead of in1weekend #1378
Conversation
|
Hey @trevordblack — this was your project; do you want to review this? |
books/RayTracingInOneWeekend.html
Outdated
| @@ -66,8 +66,8 @@ | |||
| Graphics_ by Steve Marschner and Peter Shirley, or _Computer Graphics: Principles and Practice_ | |||
| by J.D. Foley and Andy Van Dam. | |||
|
|
|||
| Peter maintains a site related to this book series at <https://in1weekend.blogspot.com/>, which | |||
| includes further reading and links to resources. | |||
| Further readings and links to resources can found at the project's | |||
There was a problem hiding this comment.
...resources can found at...
can be found at
books/RayTracingInOneWeekend.html
Outdated
| Peter maintains a site related to this book series at <https://in1weekend.blogspot.com/>, which | ||
| includes further reading and links to resources. | ||
| Further readings and links to resources can found at the project's | ||
| <a href="https://github.com/RayTracing/raytracing.github.io/wiki/Further-Readings#ray-tracing-in-one-weekend">wiki</a>. |
There was a problem hiding this comment.
You can use Markdown syntax here too:
[wiki](https://github.com/RayTracing/raytracing.github.io/wiki/Further-Readings#ray-tracing-in-one-weekend)
books/RayTracingTheNextWeek.html
Outdated
| simplest approach in each design decision I make. Check <https://in1weekend.blogspot.com/> for | ||
| readings and references to a more sophisticated approach. However, I strongly encourage you to do no | ||
| simplest approach in each design decision I make. Check the project's | ||
| <a href="https://github.com/RayTracing/raytracing.github.io/wiki/Further-Readings#ray-tracing-the-next-week">wiki</a> |
There was a problem hiding this comment.
Since the wiki gets referenced twice in this file, consider declaring this at the bottom of the file (next to the links to stb_image and the authors' accounts):
[wiki]: https://github.com/RayTracing/raytracing.github.io/wiki/Further-Readings#ray-tracing-the-next-week
Then you can reference it like so:
...See the project's [wiki][] for pointers...
You could do this for the other files too if it helps with formatting.
There was a problem hiding this comment.
Yes, Arman's right. I much prefer descriptive links instead of bare links, and using the footnote link style helps keep the bare text readable. In addition, I always like widening URLs to provide both a more descriptive link as well as a fatter click target.
I'd do something like this:
See [our Further Reading wiki page][wiki-further] for additional references to more sophisticated approaches.
…
[wiki-further]: https://github.com/RayTracing/raytracing.github.io/wiki/Further-Readings
There was a problem hiding this comment.
I'm hesitant to add ... for additional references to more sophisticated approaches., because (in my opinion) it sounds like the further readings wiki is limited to only things related in the books.
See [our Further Reading wiki page][wiki-further] for additional resources and references to more sophisticated approaches.
would be fine, or
See [our Further Reading wiki page][wiki-further] for additional project related resources.
This is a very minor point, and certainly not a hill I'm willing to die on :)
There was a problem hiding this comment.
Either of those sound fine.
books/RayTracingTheNextWeek.html
Outdated
| simplest approach in each design decision I make. Check <https://in1weekend.blogspot.com/> for | ||
| readings and references to a more sophisticated approach. However, I strongly encourage you to do no | ||
| simplest approach in each design decision I make. Check the project's | ||
| <a href="https://github.com/RayTracing/raytracing.github.io/wiki/Further-Readings#ray-tracing-the-next-week">wiki</a> |
There was a problem hiding this comment.
Yes, Arman's right. I much prefer descriptive links instead of bare links, and using the footnote link style helps keep the bare text readable. In addition, I always like widening URLs to provide both a more descriptive link as well as a fatter click target.
I'd do something like this:
See [our Further Reading wiki page][wiki-further] for additional references to more sophisticated approaches.
…
[wiki-further]: https://github.com/RayTracing/raytracing.github.io/wiki/Further-Readings
|
Oh, also a general comment — let's just point to the wiki page right now without using anchor points. My gut feeling is that our further reading section should stand on its own, independent of the books. That is, rather than organizing the references by the current status of our book outline, group them by topic within ray tracing. This is especially true because the organization of our books seems to be under constant flux, and I'd rather not worry about keeping these synchronized as we move things around. Items which are very specific to book content should appear with the books themselves (perhaps as a footnote or other inline reference). |
Addresses #1217 (also addresses ##676)
Created a Further-Readings section in the wiki, and used an anchor tag to link to the relevant sections (Book 1, etc).
Unfortunately the URL length is almost longer than the style guide line length... Page seems to render just fine, but it could be worth exploring an alternative (URL shortener, relative path?, etc)