From 7ab89a975aa15ac0e0e1dc83680bb29000f7f772 Mon Sep 17 00:00:00 2001 From: Olaf Date: Mon, 14 Oct 2024 09:03:33 +0200 Subject: [PATCH] Split Contributing --- CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 73 +----------------------------------------------- 2 files changed, 75 insertions(+), 72 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c2d4558 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,74 @@ +# Contributing to this document. + +To allow for crowdsourcing the curation we have created a [git repository](https://github.com/internetsociety/IETF-Ornithology/) for the document. + +The source for this document can be found in the [src directory](https://github.com/InternetSociety/IETF-Ornithology/tree/main/src) of the +[https://github.com/internetsociety/IETF-Ornithology/](https://github.com/internetsociety/IETF-Ornithology/) repository. Readers are encouraged to contribute by opening [issues](https://github.com/InternetSociety/IETF-Ornithology/issues) or, for those experienced with github, issuing pull requests. + + +## Technical details +### Local building + +For local development: The web and PDF version of this document can be created locally. To generate these from their markdow source use [mdBook](https://rust-lang.github.io/mdBook/cli/init.html) with the [mdbook-pandoc](https://github.com/max-heller/mdbook-pandoc) extension. This tooling is dependent on having [LuaTeX](https://www.luatex.org/), [pandoc](https://pandoc.org/), and the [Hind-Light font](https://fonts.google.com/specimen/Hind) installed. + +On OSX you can set up the environment, assuming you installed [homebrew](https://brew.sh/), by executing the following commands. + +``` +brew install rust pandoc mdbook mactex + +# make sure the mactex paths are set: +eval "$(/usr/libexec/path_helper)" + +cargo install mdbook-pandoc +echo 'PATH="/Users/olaf/.cargo/bin:$PATH"' > ~/.zshrc +export PATH="/Users/olaf/.cargo/bin:$PATH" + +``` + +The Hind font you have to install through the font install tools of your OS. + +Once that is done - you can just run ```mdbook build``` from the root of this directory. + + +### Tools and conventions + +The markdown files are created with the working group acronym as their name. Their content follows the following template. + + +``` +# The Title of the document + +Content update by script below +* [About GROUP](https://datatracker.ietf.org/group/group/about/) +* keywords: keywords, and trigger words. + +Description with an indication of elements +that may be noteworthy + + +``` +### Utility Scripts + +These are a few quick and dirty python scripts to scrape the datatracker. + +#### AgendaUpdate.py + +You can run the AgendaUpdate.py tool to update the agenda information between the <IETFschedule> XML elements. Type `AgendaUpdate.py -h` for usage information. A quick and dirty approach to updating the meeting information could be: + +`find src/IETF -name "*.md" -exec ./AgendaUpdate.py 120 America/Vancouver {} \;` + +similarly the <IETFschedule> information can be cleared using a command like + +`find src -name "*.md" -exec sed -i .bak 's/.*.*<\/IETFschedule>/* Schedule Unknown<\/IETFschedule>/' {} \;` + +#### NewWGs.py + +NewWGs.py can be used to figure out which working group are rechartered since last IETF. The following command could be used to generate a list of new working groups since IETF 120 that can be pasted into src/IETF/NewWG.md + +`./NewWGs.py 120 | sort ` + +#### ProposedWG.py + +ProposedWGs.py scrapes the datatracker for working groups that are currently being charted, also to be used for content to be copied into src/IETF/NewWG.md + +`./ProposedWGs.py | sort ` \ No newline at end of file diff --git a/README.md b/README.md index fa8e38a..b7ab7f2 100644 --- a/README.md +++ b/README.md @@ -7,75 +7,4 @@ You can read the Ornithology through as a [web page](https://internetsociety.git ## Contributing to this document. -To allow for crowdsourcing the curation we have created a [git repository](https://github.com/internetsociety/IETF-Ornithology/) for the document. - -The source for this document can be found in the [src directory](https://github.com/InternetSociety/IETF-Ornithology/tree/main/src) of the -[https://github.com/internetsociety/IETF-Ornithology/](https://github.com/internetsociety/IETF-Ornithology/) repository. Readers are encouraged to contribute by opening [issues](https://github.com/InternetSociety/IETF-Ornithology/issues) or, for those experienced with github, issuing pull requests. - - - -## Local building - -For local development: The web and PDF version of this document can be created locally. To generate these from their markdow source use [mdBook](https://rust-lang.github.io/mdBook/cli/init.html) with the [mdbook-pandoc](https://github.com/max-heller/mdbook-pandoc) extension. This tooling is dependent on having [LuaTeX](https://www.luatex.org/), [pandoc](https://pandoc.org/), and the [Hind-Light font](https://fonts.google.com/specimen/Hind) installed. - -On OSX you can set up the environment, assuming you installed [homebrew](https://brew.sh/), by executing the following commands. - -``` -brew install rust pandoc mdbook mactex - -# make sure the mactex paths are set: -eval "$(/usr/libexec/path_helper)" - -cargo install mdbook-pandoc -echo 'PATH="/Users/olaf/.cargo/bin:$PATH"' > ~/.zshrc -export PATH="/Users/olaf/.cargo/bin:$PATH" - -``` - -The Hind font you have to install through the font install tools of your OS. - -Once that is done - you can just run ```mdbook build``` from the root of this directory. - - -### Tools and conventions - -The markdown files are created with the working group acronym as their name. Their content follows the following template. - - -``` -# The Title of the document - -Content update by script below -* [About GROUP](https://datatracker.ietf.org/group/group/about/) -* keywords: keywords, and trigger words. - -Description with an indication of elements -that may be noteworthy - - -``` -## Utility Scripts - -These are a few quick and dirty python scripts to scrape the datatracker. - -### AgendaUpdate.py - -You can run the AgendaUpdate.py tool to update the agenda information between the <IETFschedule> XML elements. Type `AgendaUpdate.py -h` for usage information. A quick and dirty approach to updating the meeting information could be: - -`find src/IETF -name "*.md" -exec ./AgendaUpdate.py 120 America/Vancouver {} \;` - -similarly the <IETFschedule> information can be cleared using a command like - -`find src -name "*.md" -exec sed -i .bak 's/.*.*<\/IETFschedule>/* Schedule Unknown<\/IETFschedule>/' {} \;` - -### NewWGs.py - -NewWGs.py can be used to figure out which working group are rechartered since last IETF. The following command could be used to generate a list of new working groups since IETF 120 that can be pasted into src/IETF/NewWG.md - -`./NewWGs.py 120 | sort ` - -### ProposedWG.py - -ProposedWGs.py scrapes the datatracker for working groups that are currently being charted, also to be used for content to be copied into src/IETF/NewWG.md - -`./ProposedWGs.py | sort ` \ No newline at end of file +See [CONTRIBUTING.md](./CONTRIBUTING.md). \ No newline at end of file