Split project/crate README

.reuse/dep5

@@ -3,7 +3,7 @@ Upstream-Name: The `magic` Rust crate
 Upstream-Contact: robot9001 <[email protected]>
 Source: https://github.com/robo9k/rust-magic
 
-Files: Cargo.toml Cargo.lock README.md LICENSE.md CONTRIBUTING.md CHANGELOG.md SECURITY.md
+Files: Cargo.toml Cargo.lock README.md README-crate.md LICENSE.md CONTRIBUTING.md CHANGELOG.md SECURITY.md
 Copyright: © The `magic` Rust crate authors
 License: MIT OR Apache-2.0
 

Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "magic"
 description = "High level bindings for the `libmagic` C library"
+readme = "README-crate.md"
 license = "MIT OR Apache-2.0"
 keywords = [
     "magic",

README-crate.md

@@ -0,0 +1,76 @@
+
+[//]: # (This is the README for the `magic` crate only)
+
+[//]: # (The whole project has docs in https://github.com/robo9k/rust-magic )
+
+High-level bindings for `libmagic`
+
+# About
+
+This crate provides bindings for the [`libmagic` C library]((https://www.darwinsys.com/file/)),
+which recognizes the type of data contained in a file (or buffer) and can give you
+a textual description, a MIME type and the usual file extensions.
+
+# Usage
+
+```rust
+// only for Rust Edition 2018, see https://doc.rust-lang.org/edition-guide/rust-2021/prelude.html
+use std::convert::TryInto;
+
+fn file_example() -> Result<(), Box<dyn std::error::Error>> {
+    // Open a new configuration with flags
+    let cookie = magic::Cookie::open(magic::cookie::Flags::ERROR)?;
+
+    // Load a specific database
+    // (so exact test text assertion below works regardless of the system's default database version)
+    let database = &["data/tests/db-images-png"].try_into()?;
+    // You can instead load the default database
+    //let database = &Default::default();
+
+    let cookie = cookie.load(database)?;
+
+    let file = "data/tests/rust-logo-128x128-blk.png";
+
+    // Analyze the file
+    assert_eq!(cookie.file(file)?, "PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced");
+
+    Ok(())
+}
+```
+
+Check the [crate rustdoc](https://docs.rs/magic) for more details.
+
+# Repository
+
+The project's repository is [github.com/robo9k/rust-magic](https://github.com/robo9k/rust-magic)
+
+It contains the latest in-development version of the `magic` crate (might not be published to `crates.io` yet),  
+more [examples](https://github.com/robo9k/rust-magic/tree/main/examples) how to use the `magic` crate  
+as well as [issues](https://github.com/robo9k/rust-magic/issues)
+and [discussions](https://github.com/robo9k/rust-magic/discussions).
+
+# MSRV
+
+The Minimum Supported Rust Version (MSRV) is Rust 1.56 or higher.
+
+This version might be changed in the future, but it will be done with a crate version bump.
+
+# Requirements
+
+By default, compiling the `magic` crate will (via the [`magic-sys` crate](https://crates.io/crates/magic-sys))
+search your system library paths for a shared library version of `libmagic` to link against.  
+For this to work, you need to install the development version of `libmagic` in a standard location:
+```shell
+$ # On Debian based Linux systems:
+$ sudo apt-get install libmagic1 libmagic-dev
+
+$ # On macOS:
+$ brew install libmagic
+
+$ # On Windows:
+$ cargo install cargo-vcpkg
+$ cargo vcpkg build
+```
+
+If you're cross-compiling, or need more control over which library is selected,
+see [how to build `magic-sys`](https://crates.io/crates/magic-sys#building).

README.md

@@ -1,78 +1,53 @@
+
+[//]: # (This is the README for the whole project / Git repo)
+
+[//]: # (The crate has a separate README-crate.md )
+
 rust-magic [![build status](https://github.com/robo9k/rust-magic/actions/workflows/build.yml/badge.svg)](https://github.com/robo9k/rust-magic/actions/workflows/linux.yml) [![Documentation](https://docs.rs/magic/badge.svg)](https://docs.rs/magic) [![REUSE status](https://api.reuse.software/badge/github.com/robo9k/rust-magic)](https://api.reuse.software/info/github.com/robo9k/rust-magic) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5709/badge)](https://bestpractices.coreinfrastructure.org/projects/5709) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/robo9k/rust-magic/badge)](https://securityscorecards.dev/viewer/?uri=github.com/robo9k/rust-magic) [![codecov](https://codecov.io/gh/robo9k/rust-magic/graph/badge.svg?token=YnazJQdLXI)](https://codecov.io/gh/robo9k/rust-magic) 
 ==========
-[libmagic](https://www.darwinsys.com/file/) bindings for [Rust](https://www.rust-lang.org/).
 
+[`libmagic`](https://www.darwinsys.com/file/) bindings for the [Rust programming language](https://www.rust-lang.org/).
+
+`libmagic` recognizes the type of data contained in a file (or buffer) and can give you
+a textual description, a MIME type and the usual file extensions.
 
 # Usage
 
-This [`magic` crate](https://crates.io/crates/magic) is published on the `crates.io` Rust package registry.
+This project's [crate](https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html) is
+published on the [`crates.io` Rust package registry](https://crates.io/): the [`magic` crate](https://crates.io/crates/magic)
 
-Use [`cargo add`](https://blog.rust-lang.org/2022/06/30/Rust-1.62.0.html#cargo-add) to [specify dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html):
+In your Rust project, use [`cargo add`](https://blog.rust-lang.org/2022/06/30/Rust-1.62.0.html#cargo-add)
+to [specify dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html):
 
 ```shell
 $ cargo add magic
 ```
 
+To install the latest in-development version instead:
+```shell
+$ cargo add --git https://github.com/robo9k/rust-magic
+```
+
 You might be familiar with `libmagic`'s CLI; `file`:
 ```shell
 $ file data/tests/rust-logo-128x128-blk.png
 data/tests/rust-logo-128x128-blk.png: PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced
 ```
 
-You can implement something similar in Rust with the `magic` crate (see [examples/file-ish.rs](examples/file-ish.rs)):
-```rust
-// only for Rust Edition 2018, see https://doc.rust-lang.org/edition-guide/rust-2021/prelude.html
-use std::convert::TryInto;
-
-fn file_example() -> Result<(), Box<dyn std::error::Error>> {
-    // Open a new configuration with flags
-    let cookie = magic::Cookie::open(magic::cookie::Flags::ERROR)?;
-
-    // Load a specific database
-    // (so exact test text assertion below works regardless of the system's default database version)
-    let database = &["data/tests/db-images-png"].try_into()?;
-    // You can instead load the default database
-    //let database = &Default::default();
-
-    let cookie = cookie.load(database)?;
+You can implement something similar in Rust with the `magic` crate, see [crate README](README-crate.md):
 
-    let file = "data/tests/rust-logo-128x128-blk.png";
-
-    // Analyze the file
-    assert_eq!(cookie.file(file)?, "PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced");
-
-    Ok(())
-}
-```
 ```shell
 $ cargo run --example file-ish -- data/tests/rust-logo-128x128-blk.png
 PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced
 ```
 
-Read the [`magic` rustdoc](https://docs.rs/magic/#usage-example) for further examples and info.
-
-# MSRV
-
-The Minimum Supported Rust Version (MSRV) is Rust 1.56 or higher.
-
-This version might be changed in the future, but it will be done with a crate version bump.
+For more details, check the `magic` [rustdoc](https://doc.rust-lang.org/rustdoc/index.html): [robo9k.github.io/rust-magic/magic](https://robo9k.github.io/rust-magic/magic/index.html)
 
 # Requirements
 
-By default, compiling the `magic` crate will search your system library paths for a shared library version of `libmagic` to link against. For this to work, you need to install the development version of `libmagic` in a standard location:
-```shell
-$ # On Debian based Linux systems:
-$ sudo apt-get install libmagic1 libmagic-dev
-
-$ # On MacOs:
-$ brew install libmagic
-
-$ # On Windows:
-$ cargo install cargo-vcpkg
-$ cargo vcpkg build
-```
+For the `magic` crate requirements, see [crate README](README-crate.md).
 
-If you're cross-compiling, or need more control over which library is selected, see [how to build `magic-sys`](https://github.com/robo9k/rust-magic-sys#building).
+For developing the `rust-magic` project, see [CONTRIBUTING](CONTRIBUTING.md).
 
 # License
 
@@ -84,12 +59,12 @@ This project is licensed under either of
 
 at your option.
 
-For further details, see [LICENSE.md](LICENSE.md).
+For further details, see [LICENSE](LICENSE.md).
 
 # Security
 
-See [SECURITY.md](SECURITY.md).
+See [SECURITY](SECURITY.md).
 
 # Contribution
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING](CONTRIBUTING.md).

src/lib.rs

@@ -70,6 +70,8 @@
 //! Note that while some `libmagic` functions return somewhat structured text, e.g. MIME types and file extensions,
 //! the `magic` crate does not attempt to parse them into Rust data types since the format is not guaranteed by the C FFI API.
 //!
+//! Check the [crate README](https://crates.io/crates/magic) for required dependencies and MSRV.
+//!
 //! # Safety
 //!
 //! This crate is a binding to the `libmagic` C library and as such subject to its security problems.
@@ -825,5 +827,5 @@ mod tests {
 }
 
 #[cfg(doctest)]
-#[doc=include_str!("../README.md")]
+#[doc=include_str!("../README-crate.md")]
 mod readme {}