[WIP] The yellow paper is hard to read

ethereum / yellowpaper

The "Yellow Paper": Ethereum's formal specification

Creative Commons Attribution Share Alike 4.0 International

1.65k stars 513 forks source link

[WIP] The yellow paper is hard to read #329

Open jamesray1 opened 7 years ago

jamesray1 commented 7 years ago

[x] Add hyperref with PR #345, which has moved to https://github.com/jamesray1/yellowpaper/commits/master, along with the second and last points below.
[ ] Use the hyperref package, e.g. add cross-references, change external links, etc., using the guides here, here, here and here. The first looks like it's the most comprehensive.
[ ] Add a glossary of all symbols. Issues #272 & #23.
[ ] Add table of contents. Issue #292
[ ] Section and paragraph numbers. Issue #319
[ ] Add an index. Issue #272
[ ] Reread and where necessary, add clarifications e.g. with examples, footnotes, rewording to avoid ambiguity, etc.

I want to emphasise the importance of having good, clear documentation for Ethereum so that people who are looking to help with development, like myself, can get up to speed more quickly. At the moment, reading through it there is a lot of scrolling back and forth. For points that take a long time to understand and have to be re-read multiple times, it might be good to have examples, footnotes, etc.

pirapira commented 7 years ago

An issue about introducing links https://github.com/ethereum/yellowpaper/issues/244 (it's possible in LaTeX too).

jamesray1 commented 7 years ago

https://github.com/jamesray1/yellowpaper/commits/master

courajs commented 7 years ago

Is it possible to have sections linkable externally? It would make a huge difference to be able to link to the formal reference in Stack Exchange answers, etc.

jamesray1 commented 7 years ago

Agreed. Have a look a the hyperref docs or ask on TeX Stack Exchange to see if that can be done, and if so, how.

On Wed, 1 Nov 2017 at 07:26 Aaron Sikes notifications@github.com wrote:

Is it possible to have sections linkable externally? It would make a huge difference to be able to link to the formal reference in Stack Exchange answers, etc.

— You are receiving this because you modified the open/close state.

Reply to this email directly, view it on GitHub https://github.com/ethereum/yellowpaper/issues/329#issuecomment-340895932, or mute the thread https://github.com/notifications/unsubscribe-auth/AQLwutaTeZjGbv4JjtHgfGAL2gXuTfW1ks5sx4JmgaJpZM4PKssA .

--

Kind regards,

James Ray

Website: about.me/james.ray