chore: Onemoretryatorgreadme (#69)

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -8,7 +8,7 @@ body:
       label: Did you check the docs?
       description: Make sure you read all the docs before submitting a feature request
       options:
-        - label: I have read all the freesound-credits README.md
+        - label: I have read all the freesound-credits README
           required: true
 
   - type: textarea

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -17,8 +17,6 @@ Team member before any CI builds will run.
 - [ ] Read the [Code Of Conduct](/CODE_OF_CONDUCT.md) (required)
 - [ ] Include tests for your changes (if necessary)
 - [ ] `pre-commit run --all-files` returns no issues (required)
-- [ ] Spell-check with `cargo spellcheck check` (required)
-- [ ] Update the `spellcheck.dic` (if necessary)
 - [ ] Update any related documentation and include any relevant screenshots
 - [ ] Use [Conventional
 Commits](https://www.conventionalcommits.org/en/v1.0.0/) (required)

.github/workflows/ci.yml

@@ -108,21 +108,21 @@ jobs:
       - name: cargo docs
         run: cargo doc --no-deps --document-private-items --all-features --workspace --examples
 
-  check-spelling:
-    name: check-spelling
-    needs: basics
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Install Rust ${{ env.rust_stable }}
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          toolchain: ${{ env.rust_stable }}
-      - name: Install cargo-spellcheck
-        uses: taiki-e/install-action@v2
-        with:
-          tool: cargo-spellcheck
-      - uses: actions/checkout@v4
-      - name: cargo spellcheck
-        run: cargo spellcheck --code 1
+  # check-spelling:
+  #   name: check-spelling
+  #   needs: basics
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Checkout repository
+  #       uses: actions/checkout@v4
+  #     - name: Install Rust ${{ env.rust_stable }}
+  #       uses: dtolnay/rust-toolchain@stable
+  #       with:
+  #         toolchain: ${{ env.rust_stable }}
+  #     - name: Install cargo-spellcheck
+  #       uses: taiki-e/install-action@v2
+  #       with:
+  #         tool: cargo-spellcheck
+  #     - uses: actions/checkout@v4
+  #     - name: cargo spellcheck
+  #       run: cargo spellcheck --code 1

Cargo.toml

@@ -8,7 +8,7 @@ authors = ["Andrea C From The App"]
 homepage = "https://andreacfromtheapp.github.io/apps/freesound-credits"
 repository = "https://github.com/andreacfromtheapp/freesound-credits"
 description = "A simple command line utility to credit Freesound samples in a usable markdown file"
-readme = "README.md"
+readme = "README.org"
 keywords = ["freesound", "creative-commons", "credits"]
 categories = ["command-line-utilities"]
 
@@ -36,8 +36,8 @@ pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }.{ archive
 bin-dir = "{ bin }{ binary-ext }"
 pkg-fmt = "zip"
 
-[package.metadata.spellcheck]
-config = "spellcheck.toml"
+# [package.metadata.spellcheck]
+# config = "spellcheck.toml"
 
 [workspace.metadata.dist]
 # The preferred cargo-dist version to use in CI (Cargo.toml SemVer syntax)

README.org

@@ -0,0 +1,133 @@
+* freesound-credits
+:PROPERTIES:
+:CUSTOM_ID: freesound-credits
+:END:
+A command line utility to help you credit [[https://freesound.org][Freesound]] samples for a given project
+more easily.
+
+[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/commitlint.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/commitlint.yml/badge.svg]]
+[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/ci.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/ci.yml/badge.svg]]
+[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/trufflehog.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/trufflehog.yml/badge.svg]]
+[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release-plz.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release-plz.yml/badge.svg]]
+[[https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release.yml][https://github.com/andreacfromtheapp/freesound-credits/actions/workflows/release.yml/badge.svg]]
+[[https://crates.io/crates/freesound-credits][https://img.shields.io/crates/v/freesound%2Dcredits.svg]]
+[[https://opensource.org/licenses/Apache-2.0][https://img.shields.io/badge/License-Apache_2.0-blue.svg]]
+
+** Giving credits
+:PROPERTIES:
+:CUSTOM_ID: giving-credits
+:END:
+Giving credits in the [[https://creativecommons.org][Creative Commons]] community is often the sole requirement
+to freely use samples in your own creations. This tool helps you abide to
+[[https://en.wikipedia.org/wiki/Copyleft][Copyleft]] and credit the generous artists who contribute to [[https://freesound.org][Freesound]], and help
+you being more creative.
+
+Until today, giving credits may have been a process that you begrudged. This may
+have been stopping you from giving credits altogether. Not because you didn't
+want to, but because it was cumbersome and tedious.
+
+Not anymore! Thanks to =freesound-credits= it takes seconds now!
+
+** Install
+:PROPERTIES:
+:CUSTOM_ID: install
+:END:
+Use [[https://github.com/cargo-bins/cargo-binstall][=cargo binstall=]] to install =freesound-credits= directly from GitHub:
+
+#+begin_src shell
+cargo binstall freesound-credits
+#+end_src
+
+*** Homebrew
+:PROPERTIES:
+:CUSTOM_ID: homebrew
+:END:
+On Linux and macOS homebrew is also available:
+
+#+begin_src shell
+brew install andreacfromtheapp/tap/freesound-credits
+#+end_src
+
+** Usage
+:PROPERTIES:
+:CUSTOM_ID: usage
+:END:
+The command line comes with a straight-forward usage function:
+
+#+begin_src sh
+freesound-credits -h
+#+end_src
+
+*** Usage example
+:PROPERTIES:
+:CUSTOM_ID: usage-example
+:END:
+1. open your favorite terminal.
+2. =cd= to the folder where you want to save the credits file.
+3. run =freesound-credits= on your desired samples folder.
+4. if necessary, use the absolute path to the samples folder.
+
+**** Ableton Example
+
+Running against an Ableton =Samples/Imported= directory, will generate a
+markdown file named =field-notes-credits.md= in the current directory.
+
+#+begin_src sh
+  freesound-credits -p Samples/Imported/ -t "Field Notes" -a "Aner Andros" -d "2017-10-28"
+#+end_src
+
+** Supported file names
+:PROPERTIES:
+:CUSTOM_ID: supported-file-names
+:END:
+=freesound-credits= matches samples adhering to Freesound naming standard that
+kept their original samples names per downloads from the platform. For example:
+
+- new standard with double underscore: =69604__timkahn__subverse_whisper.wav=
+- old standard with single underscore: =2166_suburban_grilla_bowl_struck.flac=
+
+** Supported DAWs
+:PROPERTIES:
+:CUSTOM_ID: supported-daws
+:END:
+=freesound-credits= should work for any samples stored in a flat folder.
+=freesound-credits= filters out metadata files associated with audio imports. To
+add more DAWs and associated metadata or extraction, please [[https://github.com/gacallea/freesound-credits/issues/new?assignees=&labels=enhancement&projects=&template=add_a_new_daw.yml&title=feat%28DAW%29%3A+add+][file an issue]].
+
+| DAW         | Samples Folder     | Metadata    | Extraction | Notes             |
+|-------------+--------------------+-------------+------------+-------------------|
+| Ableton     | =Samples/Imported= | =.asd=      | no         |                   |
+| Reaper      | =Audio Files=      | =.reapeaks= | no         |                   |
+| Renoise     | =SamplesData=      | no          | =unzip=    | [[#renoise-extraction][extraction]]        |
+| Logic Pro X | =Audio Files=      | no          | no         | [[https://www.youtube.com/watch?v=33zVydB4MiI][Package vs Folder]] |
+
+*** Adding more DAWs
+:PROPERTIES:
+:CUSTOM_ID: adding-more-daws
+:END:
+I did the best I could with what I have. I've tested it with Ableton, Reaper,
+and Renoise projects on macOS. Logic Pro X uses no metadata and a clean Audio
+files folder, thus I decided to add it but it hasn't been tested.
+
+However, any DAW with these characteristics should work out of the box. I would
+appreciate anybody confirming more DAWs or [[https://github.com/gacallea/freesound-credits/issues/new?assignees=&labels=enhancement&projects=&template=add_a_new_daw.yml&title=feat%28DAW%29%3A+add+][adding new ones]]. When you do request
+or add a new DAW, please keep the [[#supported-daws][above table]] and the [[#extra-daws-steps][extra steps]] section in
+mind for any extra information.
+
+** Extra DAWs steps
+:PROPERTIES:
+:CUSTOM_ID: extra-daws-steps
+:END:
+*** Renoise extraction
+:PROPERTIES:
+:CUSTOM_ID: renoise-extraction
+:END:
+Extract with =unzip your_project.xrns= first. Once unzipped, you will find a
+=Song.xml= file and a =SamplesData= directory containing each =Instrument=.
+
+** Contributing
+:PROPERTIES:
+:CUSTOM_ID: contributing
+:END:
+Thanks for your help improving the project! :balloon: Happy to have you! Peruse
+the [[./docs/CONTRIBUTING.md][contributing guide]] to help you get involved in the project.

docs/CONTRIBUTING.org

@@ -135,7 +135,6 @@ guaranteeing contracts before committing any changes.
 - Install [[https://github.com/rust-secure-code/cargo-auditable][=cargo auditable=]]: =cargo install cargo-auditable --locked=
   - Set up a [[https://github.com/rust-secure-code/cargo-auditable?tab=readme-ov-file#can-i-make-cargo-always-build-with-cargo-auditable][shell alias for =cargo auditable=]]
 - Install [[https://embarkstudios.github.io/cargo-deny/][=cargo deny=]]: =cargo install cargo-deny --locked=
-- Install [[https://github.com/drahnr/cargo-spellcheck][=cargo-spellcheck=]]: =cargo install cargo-spellcheck --locked=
 - Install [[https://trufflesecurity.com/trufflehog][=trufflehog=]]: =brew install trufflehog=
   - Otherwise, download a binary from [[https://github.com/trufflesecurity/trufflehog/releases][=trufflehog= release page]].
 - Install [[https://pre-commit.com][=pre-commit=]]: =pip install pre-commit=
@@ -201,29 +200,6 @@ pre-commit run --all-files
 
 *Should it present any warning or issue: please fix, rinse, and repeat.*
 
-*** Performing spell-check on the codebase
-:PROPERTIES:
-:CUSTOM_ID: performing-spell-check-on-the-codebase
-:END:
-To perform spell-check on the codebase, run:
-
-#+begin_src shell
-cargo spellcheck checkout
-#+end_src
-
-For details of how to use the spellcheck tool, visit [[https://github.com/drahnr/cargo-spellcheck][cargo-spellcheck
-repository]].
-
-Should the command decline a word, you should backtick the declined word if code
-related. If not, the rejected word should go into =spellcheck.dic= file.
-
-#+begin_quote
-[!IMPORTANT]
-When you add a word into the file, you should also update
-the first line which tells the spellcheck tool the total number of words
-included in the file
-#+end_quote
-
 *** Testing
 :PROPERTIES:
 :CUSTOM_ID: testing

docs/RATIONALE.org

@@ -101,10 +101,9 @@ legacy and stagnation, as =AppSec= best practices dictate.
 :END:
 Besides standardized [[https://www.rust-lang.org/tools][tooling]] and [[https://doc.rust-lang.org/beta/style-guide/index.html][conventions]], default =rustfmt= and =clippy=,
 this project relies on [[https://rustsec.org][RustSec]] to inspect supply chain, and [[https://trufflesecurity.com][=trufflehog=]] to
-avoid sharing secrets in the code base. To fix [[https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments][the crate documentation comments]]
-and avoid typos in the source tree, this project relies on =cargo-spellcheck=.
-Likewise, this project relies on [[https://github.com/DavidAnson/markdownlint-cli2][=markdownlint-cli2=]] and [[https://github.com/pre-commit/pre-commit-hooks][=pre-commit-hooks=]]. All
-conveniently enforced with [[https://githooks.com][Git Hooks]].
+avoid sharing secrets in the code base. Likewise, this project relies on
+[[https://github.com/DavidAnson/markdownlint-cli2][=markdownlint-cli2=]] and [[https://github.com/pre-commit/pre-commit-hooks][=pre-commit-hooks=]]. All conveniently enforced with [[https://githooks.com][Git
+Hooks]].
 
 ** Fully Automated Releases
 :PROPERTIES:

spellcheck.dic

@@ -1,4 +1,4 @@
-26
+27
 &
 +
 <
@@ -23,3 +23,4 @@ trufflehog
 homebrew
 io
 metadata
+md