Merge pull request #874 from zcash/repo-reorg

Move source and rendered files into subdirectories

Makefile

@@ -2,14 +2,14 @@
 
 .PHONY: all all-zips tag-release protocol discard
 all-zips: .Makefile.uptodate
-	echo "$(sort $(wildcard zip-*.rst) $(wildcard zip-*.md))" >.zipfilelist.new
+	echo "$(patsubst zips/%,%,$(sort $(wildcard zips/zip-*.rst) $(wildcard zips/zip-*.md)))" >.zipfilelist.new
 	diff .zipfilelist.current .zipfilelist.new || cp -f .zipfilelist.new .zipfilelist.current
 	rm -f .zipfilelist.new
-	echo "$(sort $(wildcard draft-*.rst) $(wildcard draft-*.md))" >.draftfilelist.new
+	echo "$(patsubst zips/%,%,$(sort $(wildcard zips/draft-*.rst) $(wildcard zips/draft-*.md)))" >.draftfilelist.new
 	diff .draftfilelist.current .draftfilelist.new || cp -f .draftfilelist.new .draftfilelist.current
 	rm -f .draftfilelist.new
 	$(MAKE) README.rst
-	$(MAKE) index.html $(addsuffix .html,$(filter-out README,$(basename $(sort $(wildcard *.rst) $(wildcard *.md)))))
+	$(MAKE) rendered/index.html $(addprefix rendered/,$(addsuffix .html,$(basename $(patsubst zips/%,%,$(sort $(wildcard zips/*.rst) $(wildcard zips/*.md))))))
 
 all: all-zips protocol
 
@@ -20,41 +20,41 @@ protocol:
 	$(MAKE) -C protocol
 
 discard:
-	git checkout -- '*.html' 'README.rst' 'protocol/*.pdf'
+	git checkout -- 'rendered/*.html' 'README.rst' 'rendered/protocol/*.pdf'
 
 .Makefile.uptodate: Makefile edithtml.sh
 	$(MAKE) clean
 	touch .Makefile.uptodate
 
 define PROCESSRST
-$(eval TITLE := $(shell echo '$(basename $<)' | sed -E 's|zip-0{0,3}|ZIP |;s|draft-|Draft |')$(shell grep -E '^(\.\.)?\s*Title: ' $< |sed -E 's|.*Title||'))
+$(eval TITLE := $(shell echo '$(patsubst zips/%,%,$(basename $<))' | sed -E 's|zip-0{0,3}|ZIP |;s|draft-|Draft |')$(shell grep -E '^(\.\.)?\s*Title: ' $< |sed -E 's|.*Title||'))
 rst2html5 -v --title="$(TITLE)" $< >$@
 ./edithtml.sh --rst $@
 endef
 
 define PROCESSMD
-$(eval TITLE := $(shell echo '$(basename $<)' | sed -E 's|zip-0{0,3}|ZIP |;s|draft-|Draft |')$(shell grep -E '^(\.\.)?\s*Title: ' $< |sed -E 's|.*Title||'))
+$(eval TITLE := $(shell echo '$(patsubst zips/%,%,$(basename $<))' | sed -E 's|zip-0{0,3}|ZIP |;s|draft-|Draft |')$(shell grep -E '^(\.\.)?\s*Title: ' $< |sed -E 's|.*Title||'))
 pandoc --from=markdown --to=html $< --output=$@
 ./edithtml.sh --md $@ "${TITLE}"
 endef
 
-index.html: README.rst edithtml.sh
+rendered/index.html: README.rst edithtml.sh
 	$(PROCESSRST)
 
-%.html: %.rst edithtml.sh
+rendered/%.html: zips/%.rst edithtml.sh
 	$(PROCESSRST)
 
-%.html: %.md edithtml.sh
+rendered/%.html: zips/%.md edithtml.sh
 	$(PROCESSMD)
 
-README.rst: .zipfilelist.current .draftfilelist.current makeindex.sh README.template $(wildcard zip-*.rst) $(wildcard zip-*.md) $(wildcard draft-*.rst) $(wildcard draft-*.md)
+README.rst: .zipfilelist.current .draftfilelist.current makeindex.sh README.template $(wildcard zips/zip-*.rst) $(wildcard zips/zip-*.md) $(wildcard zips/draft-*.rst) $(wildcard zips/draft-*.md)
 	./makeindex.sh | cat README.template - >README.rst
 
 .PHONY: linkcheck
 linkcheck: all-zips
 	$(MAKE) -C protocol all-specs
-	./links_and_dests.py --check $(filter-out $(wildcard draft-*.html),$(wildcard *.html)) protocol/protocol.pdf protocol/canopy.pdf protocol/heartwood.pdf protocol/blossom.pdf protocol/sapling.pdf
+	./links_and_dests.py --check $(filter-out $(wildcard rendered/draft-*.html),$(wildcard rendered/*.html)) rendered/protocol/protocol.pdf rendered/protocol/canopy.pdf rendered/protocol/heartwood.pdf rendered/protocol/blossom.pdf rendered/protocol/sapling.pdf
 
 .PHONY: clean
 clean:
-	rm -f .zipfilelist.* README.rst index.html $(addsuffix .html,$(basename $(sort $(wildcard *.rst) $(wildcard *.md))))
+	rm -f .zipfilelist.* README.rst rendered/index.html $(addprefix rendered/,$(addsuffix .html,$(basename $(patsubst zips/%,%,$(sort $(wildcard zips/*.rst) $(wildcard zips/*.md))))))

README.template

@@ -26,17 +26,17 @@ to talk about your idea.
 Participation in the Zcash project is subject to a `Code of
 Conduct <https://github.com/zcash/zcash/blob/master/code_of_conduct.md>`__.
 
-The Zcash protocol is documented in its `Protocol Specification <protocol/protocol.pdf>`__.
+The Zcash protocol is documented in its `Protocol Specification <rendered/protocol/protocol.pdf>`__.
 
-To start contributing, first read `ZIP 0 <zip-0000.rst>`__ which documents the ZIP process.
+To start contributing, first read `ZIP 0 <zips/zip-0000.rst>`__ which documents the ZIP process.
 Then clone `this repo <https://github.com/zcash/zips>`__ from GitHub, and start adding
-your draft ZIP, formatted either as reStructuredText or as Markdown.
+your draft ZIP, formatted either as reStructuredText or as Markdown, into the `zips/` directory.
 
-For example, if using reStructuredText, use a filename matching ``draft-*.rst``.
+For example, if using reStructuredText, use a filename matching ``zips/draft-*.rst``.
 Use ``make`` to check that you are using correct
 `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ or
 `Markdown <https://pandoc.org/MANUAL.html#pandocs-markdown>`__ syntax,
-and double-check the generated ``draft-*.html`` file before filing a Pull Request.
+and double-check the generated ``rendered/draft-*.html`` file before filing a Pull Request.
 See `here <protocol/README.rst>`__ for the project dependencies.
 
 

edithtml.sh

@@ -37,6 +37,10 @@ sed -i.sedbak 's|<a \(class=[^ ]* \)*href="\([^":]*\)\.rst\(\#[^"]*\)*">|<a \1hr
 sed -i.sedbak 's|<a \(class=[^ ]* \)*href="\([^":]*\)\.md\(\#[^"]*\)*">|<a \1href="\2\3">|g' "$2"
 sed -i.sedbak 's|&lt;\(https:[^&]*\)&gt;|\&lt;<a href="\1">\1</a>\&gt;|g' "$2"
 
+sed -i.sedbak 's|src="../rendered/|src="|g' "$2"
+sed -i.sedbak 's|<a href="rendered/|<a href="|g' "$2"
+sed -i.sedbak 's|<a \(class=[^ ]* \)*href="zips/|<a \1href="|g' "$2"
+
 perl -i.sedbak -p0e 's|<section id="([^"]*)">\s*.?\s*<h([1-9])>([^<]*(?:<code>[^<]*</code>[^<]*)?)</h([1-9])>|<section id="\1"><h\2><span class="section-heading">\3</span><span class="section-anchor"> <a rel="bookmark" href="#\1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h\4>|g' "$2"
 
-rm -f *.sedbak
+rm -f rendered/*.sedbak

makeindex.sh

@@ -11,6 +11,7 @@ Index of ZIPs
     <tr> <th>ZIP</th> <th>Title</th> <th>Status</th> </tr>
 EndOfHeader
 for zipfile in $(cat .zipfilelist.current); do
+  zipfile=zips/$zipfile
   echo Adding $zipfile to index. >/dev/stderr
   if grep -E '^\s*Status:\s*Reserved' $zipfile >/dev/null; then
     echo "    <tr> <td><span class=\"reserved\">`basename $(basename $zipfile .rst) .md | sed -E 's@zip-0{0,3}@@'`</span></td> <td class=\"left\"><a class=\"reserved\" href=\"`echo $zipfile`\">`grep '^\s*Title:' $zipfile | sed -E 's@\s*Title:\s*@@'`</a></td> <td>`grep '^\s*Status:' $zipfile | sed -E 's@\s*Status:\s*@@'`</td>"
@@ -40,6 +41,7 @@ be deleted.
     <tr> <th>Title</th> </tr>
 EndOfDraftHeader
   for draftfile in $(cat .draftfilelist.current); do
+    draftfile=zips/$draftfile
     echo Adding $draftfile to index of drafts. >/dev/stderr
     echo "    <tr> <td class=\"left\"><a href=\"`echo $draftfile`\">`grep '^\s*Title:' $draftfile | sed -E 's@\s*Title:\s*@@'`</a></td>"
   done

protocol/Makefile

@@ -15,6 +15,8 @@ LATEXMK=max_print_line=10000 latexmk $(LATEXMKOPT_$(ENGINE)) --halt-on-error --f
 LATEX=$(ENGINE) --halt-on-error --file-line-error
 NOCRUFT?=|perl -pe 's|[{\<\(]\/[^ ]* ?||g;s|^.* has been referenced but does not exist.*||g;s|^\n||g'
 
+PDFDIR=../rendered/protocol
+
 # Use EXTRAOPT=-pvc for "continuous preview" mode. For example, "make auxblossom EXTRAOPT=-pvc".
 # In this case the updated .pdf will be in the aux/ directory.
 
@@ -23,7 +25,7 @@ all: .Makefile.uptodate
 	$(MAKE) nu5 canopy heartwood blossom sapling
 
 all-specs: .Makefile.uptodate
-	$(MAKE) nu5.pdf canopy.pdf heartwood.pdf blossom.pdf sapling.pdf
+	$(MAKE) $(PDFDIR)/nu5.pdf $(PDFDIR)/canopy.pdf $(PDFDIR)/heartwood.pdf $(PDFDIR)/blossom.pdf $(PDFDIR)/sapling.pdf
 
 tag-release:
 ifeq ($(shell git tag --points-at HEAD |wc -l),0)
@@ -33,31 +35,31 @@ else
 	git fetch origin
 	git merge-base --is-ancestor origin/main HEAD || (echo "The current branch is dirty and/or not up-to-date with origin's main branch."; false)
 	$(MAKE) clean all
-	git add *.pdf
-	git commit -m "Regenerate PDFs." *.pdf
+	git add $(PDFDIR)/*.pdf
+	git commit -m "Regenerate PDFs." $(PDFDIR)/*.pdf
 	git tag "v$(TAG)"
 endif
 
 discard:
-	git checkout -- '*.pdf'
+	git checkout -- "$(PDFDIR)/*.pdf"
 
 .Makefile.uptodate: Makefile
 	$(MAKE) clean
 	touch .Makefile.uptodate
 
-sapling.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
+$(PDFDIR)/sapling.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
 	$(MAKE) sapling
 
-blossom.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
+$(PDFDIR)/blossom.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
 	$(MAKE) blossom
 
-heartwood.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
+$(PDFDIR)/heartwood.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
 	$(MAKE) heartwood
 
-canopy.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
+$(PDFDIR)/canopy.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
 	$(MAKE) canopy
 
-nu5.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
+$(PDFDIR)/nu5.pdf: protocol.tex zcash.bib incremental_merkle.png key_components_sapling.png
 	$(MAKE) nu5
 
 .PHONY: auxsapling
@@ -71,7 +73,7 @@ auxsapling:
 .PHONY: sapling
 sapling:
 	$(MAKE) auxsapling
-	mv -f aux/sapling.pdf .
+	mv -f aux/sapling.pdf $(PDFDIR)
 
 .PHONY: auxblossom
 auxblossom:
@@ -84,7 +86,7 @@ auxblossom:
 .PHONY: blossom
 blossom:
 	$(MAKE) auxblossom
-	mv -f aux/blossom.pdf .
+	mv -f aux/blossom.pdf $(PDFDIR)
 
 .PHONY: auxheartwood
 auxheartwood:
@@ -97,7 +99,7 @@ auxheartwood:
 .PHONY: heartwood
 heartwood:
 	$(MAKE) auxheartwood
-	mv -f aux/heartwood.pdf .
+	mv -f aux/heartwood.pdf $(PDFDIR)
 
 .PHONY: auxcanopy
 auxcanopy:
@@ -110,7 +112,7 @@ auxcanopy:
 .PHONY: canopy
 canopy:
 	$(MAKE) auxcanopy
-	mv -f aux/canopy.pdf .
+	mv -f aux/canopy.pdf $(PDFDIR)
 
 .PHONY: auxnu5
 auxnu5:
@@ -123,8 +125,8 @@ auxnu5:
 .PHONY: nu5
 nu5:
 	$(MAKE) auxnu5
-	mv -f aux/nu5.pdf .
-	cp -f nu5.pdf protocol.pdf
+	mv -f aux/nu5.pdf $(PDFDIR)
+	cp -f $(PDFDIR)/nu5.pdf $(PDFDIR)/protocol.pdf
 
 .PHONY: nolatexmk-sapling
 nolatexmk-sapling:
@@ -189,4 +191,4 @@ nolatexmk-nu5:
 
 .PHONY: clean
 clean:
-	rm -f aux/* html/* protocol.ver protocol.pdf nu5.pdf canopy.pdf heartwood.pdf blossom.pdf sapling.pdf
+	rm -f aux/* html/* protocol.ver $(PDFDIR)/protocol.pdf $(PDFDIR)/nu5.pdf $(PDFDIR)/canopy.pdf $(PDFDIR)/heartwood.pdf $(PDFDIR)/blossom.pdf $(PDFDIR)/sapling.pdf

index.html → rendered/index.html

@@ -21,8 +21,8 @@
             <p>Anyone can write a ZIP! We encourage community contributions and decentralization of work on the Zcash protocol. If you’d like to bounce ideas off people before formally writing a ZIP, we encourage it! Visit the <a href="https://discord.gg/kdjfvps">ZcashCommunity Discord chat</a> to talk about your idea.</p>
             <p>Participation in the Zcash project is subject to a <a href="https://github.com/zcash/zcash/blob/master/code_of_conduct.md">Code of Conduct</a>.</p>
             <p>The Zcash protocol is documented in its <a href="protocol/protocol.pdf">Protocol Specification</a>.</p>
-            <p>To start contributing, first read <a href="zip-0000">ZIP 0</a> which documents the ZIP process. Then clone <a href="https://github.com/zcash/zips">this repo</a> from GitHub, and start adding your draft ZIP, formatted either as reStructuredText or as Markdown.</p>
-            <p>For example, if using reStructuredText, use a filename matching <code>draft-*.rst</code>. Use <code>make</code> to check that you are using correct <a href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> or <a href="https://pandoc.org/MANUAL.html#pandocs-markdown">Markdown</a> syntax, and double-check the generated <code>draft-*.html</code> file before filing a Pull Request. See <a href="protocol/README">here</a> for the project dependencies.</p>
+            <p>To start contributing, first read <a href="zip-0000">ZIP 0</a> which documents the ZIP process. Then clone <a href="https://github.com/zcash/zips">this repo</a> from GitHub, and start adding your draft ZIP, formatted either as reStructuredText or as Markdown, into the <cite>zips/</cite> directory.</p>
+            <p>For example, if using reStructuredText, use a filename matching <code>zips/draft-*.rst</code>. Use <code>make</code> to check that you are using correct <a href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> or <a href="https://pandoc.org/MANUAL.html#pandocs-markdown">Markdown</a> syntax, and double-check the generated <code>rendered/draft-*.html</code> file before filing a Pull Request. See <a href="protocol/README">here</a> for the project dependencies.</p>
         </section>
         <section id="license"><h2><span class="section-heading">License</span><span class="section-anchor"> <a rel="bookmark" href="#license"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
             <p>Unless otherwise stated in this repository’s individual files, the contents of this repository are released under the terms of the MIT license. See <a href="COPYING">COPYING</a> for more information or see <a href="https://opensource.org/licenses/MIT">https://opensource.org/licenses/MIT</a> .</p>

zip-0032.html → rendered/zip-0032.html

@@ -534,7 +534,7 @@
                         <span class="math">\(R\)</span>
                      are the same between deriving a full viewing key, and deriving the corresponding spending key. Both of these derivations are shown in the following diagram:</p>
                     <figure class="align-center" align="center">
-                        <img width="900" src="zip-0032-sapling-internal-key-derivation.png" alt="" />
+                        <img width="900" src="assets/images/zip-0032-sapling-internal-key-derivation.png" alt="" />
                         <figcaption>Diagram of Sapling internal key derivation</figcaption>
                     </figure>
                     <p>(For simplicity, the proof authorizing key is not shown.)</p>
@@ -693,7 +693,7 @@
                     <span class="math">\(\mathsf{ovk_{internal}}\)</span>
                  fields being derived, as specified in <a id="footnote-reference-30" class="footnote_reference" href="#protocol-orchardkeycomponents">12</a> and shown in the following diagram:</p>
                 <figure class="align-center" align="center">
-                    <img width="720" src="zip-0032-orchard-internal-key-derivation.png" alt="" />
+                    <img width="720" src="assets/images/zip-0032-orchard-internal-key-derivation.png" alt="" />
                     <figcaption>Diagram of Orchard internal key derivation, also showing derivation from the parent extended spending key</figcaption>
                 </figure>
                 <p>This method of deriving internal keys is applied to external keys that are children of the Account level. It was implemented in <cite>zcashd</cite> as part of support for ZIP 316 <a id="footnote-reference-31" class="footnote_reference" href="#zip-0316">8</a>.</p>

zip-0227.html → rendered/zip-0227.html

@@ -84,7 +84,7 @@
             </ol>
             <p>The relations between these keys are shown in the following diagram:</p>
             <figure class="align-center" align="center">
-                <img width="450" src="zip-0227-key-components-zsa.png" alt="" />
+                <img width="450" src="assets/images/zip-0227-key-components-zsa.png" alt="" />
                 <figcaption>Diagram of Issuance Key Components for the Orchard-ZSA Protocol</figcaption>
             </figure>
             <section id="issuance-authorization-signature-scheme"><h3><span class="section-heading">Issuance Authorization Signature Scheme</span><span class="section-anchor"> <a rel="bookmark" href="#issuance-authorization-signature-scheme"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
@@ -294,7 +294,7 @@
              is defined as in <a id="footnote-reference-20" class="footnote_reference" href="#protocol-concretegrouphashpallasandvesta">20</a>.</p>
             <p>The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:</p>
             <figure class="align-center" align="center">
-                <img width="600" src="zip-0227-asset-identifier-relation.png" alt="" />
+                <img width="600" src="assets/images/zip-0227-asset-identifier-relation.png" alt="" />
                 <figcaption>Diagram relating the Asset Identifier, Asset Digest, and Asset Base in the ZSA Protocol</figcaption>
             </figure>
             <p><strong>Note:</strong> To keep notations light and concise, we may omit

zip-0307.html → rendered/zip-0307.html

@@ -39,7 +39,7 @@
                 <li><strong>Light client</strong> that subscribes to the stream from a proxy server and uses that data to update its own view of the chain state. The light client MAY be attached to a wallet backend that will track particular Sapling notes.</li>
             </ul>
             <figure class="align-center" align="center">
-                <img src="zip-0307-arch.png" alt="" />
+                <img src="assets/images/zip-0307-arch.png" alt="" />
                 <figcaption>Outline of the light wallet architecture</figcaption>
             </figure>
         </section>