Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@fschutt
fschutt committed Feb 5, 2018
1 parent 5c8d0b4 commit ba321bd
Show file tree
Hide file tree
Showing 2 changed files with 106 additions and 146 deletions.
126 changes: 53 additions & 73 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,100 +244,81 @@ See the CHANGELOG.md file.

## Further reading

The `PDFDocument` is hidden behind a `PDFDocumentReference`, which locks the things you can
do behind a facade. Pretty much all functions operate on a `PDFLayerReference`, so that would
be where to look for existing functions or where to implement new functions. The `PDFDocumentReference`
is a reference-counted document. It uses the pages and layers for inner mutablility, because
I ran into borrowing issues with the document. __IMPORTANT:__ All functions that mutate the state
of the document, "borrow" the document mutably for the duration of the function. It is important
that you don't borrow the document twice (your program will crash if you do so). I have prevented
this wherever possible, by making the document only public to the crate so you cannot lock it from
outside of this library.

Images have to be added to the pages resources before using them. Meaning, you can only use an image
on the page that you added it to. Otherwise, you may end up with a corrupt PDF.

Fonts are embedded using `freetype`. In the future, there should be an option to use `rusttype`.
Please report issues if you have any, especially if you see `BorrowMut` errors (they should not happen).
Kerning is currently not done, because neither `freetype` nor `rusttype` can reliably read kerning data.
However, "correct" kerning / placement requires a full font shaping engine, etc. This would be a completely
different project.

For learning how a PDF is actually made, please read the [wiki](https://github.com/sharazam/printpdf/wiki).
When I began making this library, these resources were not available anywhere, so I hope to help other people
with these topics. Reading the wiki is essential if you want to contribute to this library.
The `PDFDocument` is hidden behind a `PDFDocumentReference`, which locks
the things you can do behind a facade. Pretty much all functions operate
on a `PDFLayerReference`, so that would be where to look for existing
functions or where to implement new functions. The `PDFDocumentReference`
is a reference-counted document. It uses the pages and layers for inner
mutablility, because
I ran into borrowing issues with the document. __IMPORTANT:__ All functions
that mutate the state of the document, "borrow" the document mutably for
the duration of the function. It is important that you don't borrow the
document twice (your program will crash if you do so). I have prevented
this wherever possible, by making the document only public to the crate
so you cannot lock it from outside of this library.

Images have to be added to the pages resources before using them. Meaning,
you can only use an image on the page that you added it to. Otherwise,
you may end up with a corrupt PDF.

Fonts are embedded using `freetype`. There is a `rusttype` branch in this
repository, but `rusttype` does fails to get the height of an unscaled
font correctly, so that's why you currently have to use `freetype`

Please report issues if you have any, especially if you see `BorrowMut`
errors (they should not happen). Kerning is currently not done, because
neither `freetype` nor `rusttype` can reliably read kerning data.
However, "correct" kerning / placement requires a full font shaping
engine, etc. This would be a completely different project.

For learning how a PDF is actually made, please read the
[wiki](https://github.com/fschutt/printpdf/wiki) (currently not
completely finished). When I began making this library, these resources
were not available anywhere, so I hope to help other people
with these topics. Reading the wiki is essential if you want to
contribute to this library.

## Goals and Roadmap

The goal of printpdf is to be a general-use PDF library, such as libharu or similar.
PDFs generated by printpdf must always adhere to a PDF standard. However, not all standards
are supported. See this list:

- [ ] PDF/A-1b:2005
- [ ] PDF/A-1a:2005
- [ ] PDF/A-2:2011
- [ ] PDF/A-2a:2011
- [ ] PDF/A-2b:2011
- [ ] PDF/A-2u:2011
- [ ] PDF/A-3:2012
- [ ] PDF/UA-1
- [ ] PDF/X-1a:2001
- [x] PDF/X-3:2002
- [ ] PDF/X-1a:2003
- [ ] PDF/X-3:2003
- [ ] PDF/X-4:2010
- [ ] PDF/X-4P:2010
- [ ] PDF/X-5G:2010
- [ ] PDF/X-5PG:2010
- [ ] PDF/X-5N:2010
- [ ] PDF/E-1
- [ ] PDF/VT:2010

Over time, there will be more standards supported. Checking a PDF for errors is currently only a stub.

### Planned features
The goal of printpdf is to be a general-use PDF library, such as
libharu or similar. PDFs generated by printpdf should always adhere
to a PDF standard, except if you turn it off. Currently, only the
standard `PDF/X-3:2002` is covered (i.e. valid PDF according to Adobe
Acrobat). Over time, there will be more standards supported. Checking a
PDF for errors is currently only a stub.

### Planned features / Not done yet

The following features aren't implemented yet, most
- Clipping
- Aligning / layouting text
- Open Prepress Interface
- Halftoning images, Gradients, Patterns
- SVG / instantiated content
- More font support
- Forms, annotations
- Bookmarks / Table of contents
- Conformance / error checking for various PDF standards
- Embedded Javascript
- Reading PDF
- Completion of printpdf wiki

## Contributing

[READ THE WIKI FIRST !!!](https://github.com/sharazam/printpdf/wiki)

- Fork the project, make you own branch
- If you want to add support for some data type, let's say images or embedded video, create your type
in `/src/types/plugins/[family of your type]/[type].rs`
- The type should implement `IntoPdfObject`, so that it can be added to the document
- Change the `page` and `layer content types to have a convenience function for adding your type
- Document your changes. Add a doc test (how you expect the type to be used) and a unit test
(if the type is conform to the expected PDF type)
- If you want to change this README, change the lib.rs instead and run `cargo readme > README.md`.
- Create pull request

## Testing

Currently the testing is pretty much non-existent, because PDF is very hard to test. This should change
over time: Testing should be done in two stages. First, test the individual PDF objects, if the conversion
into a PDF object is done correctly. The second stage is manual inspection of PDF objects via Adobe Preflight.
Currently the testing is pretty much non-existent, because PDF is very hard to test.
This should change over time: Testing should be done in two stages. First, test
the individual PDF objects, if the conversion into a PDF object is done correctly.
The second stage is manual inspection of PDF objects via Adobe Preflight.

Put the tests of the first stage in /tests/mod.rs. The second stage tests are better to be handled
inside the plugins' mod.rs file. `printpdf` depends highly on [lopdf](https://github.com/J-F-Liu/lopdf),
so you can either construct your test object against a real type or a debug string of your serialized
type. Either way is fine - you just have to check that the test object is conform to what PDF expects.
Put the tests of the first stage in /tests/mod.rs. The second stage tests are
better to be handled inside the plugins' mod.rs file. `printpdf` depends highly
on [lopdf](https://github.com/J-F-Liu/lopdf), so you can either construct your
test object against a real type or a debug string of your serialized type.
Either way is fine - you just have to check that the test object is conform to
what PDF expects.

## Useful links

Here are some resources I found while working on this library
Here are some resources I found while working on this library:

[`PDFXPlorer`, shows the DOM tree of a PDF, needs .NET 2.0](http://www.o2sol.com/pdfxplorer/download.htm)

Expand All @@ -348,4 +329,3 @@ Here are some resources I found while working on this library
[PDF X/1-a Validator](https://www.pdf-online.com/osa/validate.aspx)

[PDF X/3 technical notes](http://www.pdfxreport.com/lib/exe/fetch.php?media=en:technote_pdfx_checks.pdf)

126 changes: 53 additions & 73 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -240,100 +240,81 @@
//!
//! # Further reading
//!
//! The `PDFDocument` is hidden behind a `PDFDocumentReference`, which locks the things you can
//! do behind a facade. Pretty much all functions operate on a `PDFLayerReference`, so that would
//! be where to look for existing functions or where to implement new functions. The `PDFDocumentReference`
//! is a reference-counted document. It uses the pages and layers for inner mutablility, because
//! I ran into borrowing issues with the document. __IMPORTANT:__ All functions that mutate the state
//! of the document, "borrow" the document mutably for the duration of the function. It is important
//! that you don't borrow the document twice (your program will crash if you do so). I have prevented
//! this wherever possible, by making the document only public to the crate so you cannot lock it from
//! outside of this library.
//!
//! Images have to be added to the pages resources before using them. Meaning, you can only use an image
//! on the page that you added it to. Otherwise, you may end up with a corrupt PDF.
//!
//! Fonts are embedded using `freetype`. In the future, there should be an option to use `rusttype`.
//! Please report issues if you have any, especially if you see `BorrowMut` errors (they should not happen).
//! Kerning is currently not done, because neither `freetype` nor `rusttype` can reliably read kerning data.
//! However, "correct" kerning / placement requires a full font shaping engine, etc. This would be a completely
//! different project.
//!
//! For learning how a PDF is actually made, please read the [wiki](https://github.com/sharazam/printpdf/wiki).
//! When I began making this library, these resources were not available anywhere, so I hope to help other people
//! with these topics. Reading the wiki is essential if you want to contribute to this library.
//! The `PDFDocument` is hidden behind a `PDFDocumentReference`, which locks
//! the things you can do behind a facade. Pretty much all functions operate
//! on a `PDFLayerReference`, so that would be where to look for existing
//! functions or where to implement new functions. The `PDFDocumentReference`
//! is a reference-counted document. It uses the pages and layers for inner
//! mutablility, because
//! I ran into borrowing issues with the document. __IMPORTANT:__ All functions
//! that mutate the state of the document, "borrow" the document mutably for
//! the duration of the function. It is important that you don't borrow the
//! document twice (your program will crash if you do so). I have prevented
//! this wherever possible, by making the document only public to the crate
//! so you cannot lock it from outside of this library.
//!
//! Images have to be added to the pages resources before using them. Meaning,
//! you can only use an image on the page that you added it to. Otherwise,
//! you may end up with a corrupt PDF.
//!
//! Fonts are embedded using `freetype`. There is a `rusttype` branch in this
//! repository, but `rusttype` does fails to get the height of an unscaled
//! font correctly, so that's why you currently have to use `freetype`
//!
//! Please report issues if you have any, especially if you see `BorrowMut`
//! errors (they should not happen). Kerning is currently not done, because
//! neither `freetype` nor `rusttype` can reliably read kerning data.
//! However, "correct" kerning / placement requires a full font shaping
//! engine, etc. This would be a completely different project.
//!
//! For learning how a PDF is actually made, please read the
//! [wiki](https://github.com/fschutt/printpdf/wiki) (currently not
//! completely finished). When I began making this library, these resources
//! were not available anywhere, so I hope to help other people
//! with these topics. Reading the wiki is essential if you want to
//! contribute to this library.
//!
//! # Goals and Roadmap
//!
//! The goal of printpdf is to be a general-use PDF library, such as libharu or similar.
//! PDFs generated by printpdf must always adhere to a PDF standard. However, not all standards
//! are supported. See this list:
//!
//! - [ ] PDF/A-1b:2005
//! - [ ] PDF/A-1a:2005
//! - [ ] PDF/A-2:2011
//! - [ ] PDF/A-2a:2011
//! - [ ] PDF/A-2b:2011
//! - [ ] PDF/A-2u:2011
//! - [ ] PDF/A-3:2012
//! - [ ] PDF/UA-1
//! - [ ] PDF/X-1a:2001
//! - [x] PDF/X-3:2002
//! - [ ] PDF/X-1a:2003
//! - [ ] PDF/X-3:2003
//! - [ ] PDF/X-4:2010
//! - [ ] PDF/X-4P:2010
//! - [ ] PDF/X-5G:2010
//! - [ ] PDF/X-5PG:2010
//! - [ ] PDF/X-5N:2010
//! - [ ] PDF/E-1
//! - [ ] PDF/VT:2010
//!
//! Over time, there will be more standards supported. Checking a PDF for errors is currently only a stub.
//!
//! ## Planned features
//! The goal of printpdf is to be a general-use PDF library, such as
//! libharu or similar. PDFs generated by printpdf should always adhere
//! to a PDF standard, except if you turn it off. Currently, only the
//! standard `PDF/X-3:2002` is covered (i.e. valid PDF according to Adobe
//! Acrobat). Over time, there will be more standards supported. Checking a
//! PDF for errors is currently only a stub.
//!
//! ## Planned features / Not done yet
//!
//! The following features aren't implemented yet, most
//! - Clipping
//! - Aligning / layouting text
//! - Open Prepress Interface
//! - Halftoning images, Gradients, Patterns
//! - SVG / instantiated content
//! - More font support
//! - Forms, annotations
//! - Bookmarks / Table of contents
//! - Conformance / error checking for various PDF standards
//! - Embedded Javascript
//! - Reading PDF
//! - Completion of printpdf wiki
//!
//! # Contributing
//!
//! [READ THE WIKI FIRST !!!](https://github.com/sharazam/printpdf/wiki)
//!
//! - Fork the project, make you own branch
//! - If you want to add support for some data type, let's say images or embedded video, create your type
//! in `/src/types/plugins/[family of your type]/[type].rs`
//! - The type should implement `IntoPdfObject`, so that it can be added to the document
//! - Change the `page` and `layer content types to have a convenience function for adding your type
//! - Document your changes. Add a doc test (how you expect the type to be used) and a unit test
//! (if the type is conform to the expected PDF type)
//! - If you want to change this README, change the lib.rs instead and run `cargo readme > README.md`.
//! - Create pull request
//!
//! # Testing
//!
//! Currently the testing is pretty much non-existent, because PDF is very hard to test. This should change
//! over time: Testing should be done in two stages. First, test the individual PDF objects, if the conversion
//! into a PDF object is done correctly. The second stage is manual inspection of PDF objects via Adobe Preflight.
//! Currently the testing is pretty much non-existent, because PDF is very hard to test.
//! This should change over time: Testing should be done in two stages. First, test
//! the individual PDF objects, if the conversion into a PDF object is done correctly.
//! The second stage is manual inspection of PDF objects via Adobe Preflight.
//!
//! Put the tests of the first stage in /tests/mod.rs. The second stage tests are better to be handled
//! inside the plugins' mod.rs file. `printpdf` depends highly on [lopdf](https://github.com/J-F-Liu/lopdf),
//! so you can either construct your test object against a real type or a debug string of your serialized
//! type. Either way is fine - you just have to check that the test object is conform to what PDF expects.
//! Put the tests of the first stage in /tests/mod.rs. The second stage tests are
//! better to be handled inside the plugins' mod.rs file. `printpdf` depends highly
//! on [lopdf](https://github.com/J-F-Liu/lopdf), so you can either construct your
//! test object against a real type or a debug string of your serialized type.
//! Either way is fine - you just have to check that the test object is conform to
//! what PDF expects.
//!
//! # Useful links
//!
//! Here are some resources I found while working on this library
//! Here are some resources I found while working on this library:
//!
//! [`PDFXPlorer`, shows the DOM tree of a PDF, needs .NET 2.0](http://www.o2sol.com/pdfxplorer/download.htm)
//!
Expand All @@ -344,7 +325,6 @@
//! [PDF X/1-a Validator](https://www.pdf-online.com/osa/validate.aspx)
//!
//! [PDF X/3 technical notes](http://www.pdfxreport.com/lib/exe/fetch.php?media=en:technote_pdfx_checks.pdf)
//!
#![allow(unused_doc_comment)]
#![allow(unused_variables)]
Expand Down

0 comments on commit ba321bd

Please sign in to comment.