Merge pull request #21 from fleetingbytes/develop

Develop

closes #18

Author: fleetingbytes

.gitattributes

@@ -0,0 +1 @@
+* text=auto

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 <!-- towncrier release notes start -->
 
+## 0.9.0 (2024-03-11)
+
+
+### Bugfixes
+
+- Recognize control words with where the parameter's digital sequence is delimited by any character other than an ASCII digit [#18](https://github.com/fleetingbytes/rtfparse/issues/18)
+
+
+### Development Details
+
+- Renamed a few things, improved readme [#17](https://github.com/fleetingbytes/rtfparse/issues/17)
+
 ## 0.8.2 (2024-03-05)
 
 

LICENSE.txt

@@ -1,19 +1,19 @@
-Copyright (c) 2023 Sven Siegmud
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Copyright (c) 2023 Sven Siegmud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,16 +1,20 @@
 # rtfparse
 
-RTF Parser. So far it can only de-encapsulate HTML content from an RTF, but it properly parses the RTF structure and allows you to write your own custom RTF renderers. The HTML de-encapsulator provided with `rtfparse` is just one such custom renderer which liberates the HTML content from its RTF encapsulation and saves it in a given html file.
+Parses Microsofts Rich Text Format (RTF) documents. It creates an in-memory object which represents the tree structure of the RTF document. This object can in turn be rendered by using one of the renderers.
+So far, rtfparse provides only one renderer (`Decapsulate_HTML`) which liberates the HTML code encapsulated in RTF. This will come handy, for examle, if you ever need to extract the HTML from a HTML-formatted email message saved by Microsoft Outlook.
+
+MS Outlook also tends to use RTF compression, so the CLI of rtfparse can optionally do that, too.
+
+You can of course write your own renderers of parsed RTF documents and consider contributing them to this project.
 
-rtfparse can also decompressed RTF from MS Outlook `.msg` files and parse that.
 
 # Installation
 
 Install rtfparse from your local repository with pip:
 
     pip install rtfparse
 
-Installation creates an executable file `rtfparse` in your python scripts folder which should be in your `$PATH`. 
+Installation creates an executable file `rtfparse` in your python scripts folder which should be in your `$PATH`.
 
 # Usage From Command Line
 
@@ -24,49 +28,48 @@ rtfparse.info.log
 rtfparse.errors.log
 ```
 
-## Example: De-encapsulate HTML from an uncompressed RTF file
+## Example: Decapsulate HTML from an uncompressed RTF file
 
-    rtfparse --rtf-file "path/to/rtf_file.rtf" --de-encapsulate-html --output-file "path/to/extracted.html"
+    rtfparse --rtf-file "path/to/rtf_file.rtf" --decapsulate-html --output-file "path/to/extracted.html"
 
-## Example: De-encapsulate HTML from MS Outlook email file
+## Example: Decapsulate HTML from MS Outlook email file
 
-Thanks to [extract_msg](https://github.com/TeamMsgExtractor/msg-extractor) and [compressed_rtf](https://github.com/delimitry/compressed_rtf), rtfparse internally uses them:
+For this, the CLI of rtfparse uses [extract_msg](https://github.com/TeamMsgExtractor/msg-extractor) and [compressed_rtf](https://github.com/delimitry/compressed_rtf).
 
-    rtfparse --msg-file "path/to/email.msg" --de-encapsulate-html --output-file "path/to/extracted.html"
+    rtfparse --msg-file "path/to/email.msg" --decapsulate-html --output-file "path/to/extracted.html"
 
 ## Example: Only decompress the RTF from MS Outlook email file
 
     rtfparse --msg-file "path/to/email.msg" --output-file "path/to/extracted.rtf"
 
-## Example: De-encapsulate HTML from MS Outlook email file and save (and later embed) the attachments
+## Example: Decapsulate HTML from MS Outlook email file and save (and later embed) the attachments
 
 When extracting the RTF from the `.msg` file, you can save the attachments (which includes images embedded in the email text) in a directory:
 
     rtfparse --msg-file "path/to/email.msg" --output-file "path/to/extracted.rtf" --attachments-dir "path/to/dir"
 
-In `rtfparse` version 1.x you will be able to embed these images in the de-encapsulated HTML. This functionality will be provided by the package [embedimg](https://github.com/fleetingbytes/embedimg).
+In `rtfparse` version 1.x you will be able to embed these images in the decapsulated HTML. This functionality will be provided by the package [embedimg](https://github.com/fleetingbytes/embedimg).
 
     rtfparse --msg-file "path/to/email.msg" --output-file "path/to/extracted.rtf" --attachments-dir "path/to/dir" --embed-img
 
 In the current version the option `--embed-img` does nothing.
 
-# Programatic usage in python module
+# Programatic usage in a Python module
 
 ```
 from pathlib import Path
 from rtfparse.parser import Rtf_Parser
-from rtfparse.renderers.de_encapsulate_html import De_encapsulate_HTML
+from rtfparse.renderers.html_decapsulator import HTML_Decapsulator
 
 source_path = Path(r"path/to/your/rtf/document.rtf")
-target_path = Path(r"path/to/your/html/de_encapsulated.html")
+target_path = Path(r"path/to/your/html/decapsulated.html")
 # Create parent directory of `target_path` if it does not already exist:
 target_path.parent.mkdir(parents=True, exist_ok=True)
 
-
 parser = Rtf_Parser(rtf_path=source_path)
 parsed = parser.parse_file()
 
-renderer = De_encapsulate_HTML()
+renderer = HTML_Decapsulator()
 
 with open(target_path, mode="w", encoding="utf-8") as html_file:
     renderer.render(parsed, html_file)
@@ -76,6 +79,5 @@ with open(target_path, mode="w", encoding="utf-8") as html_file:
 
 If you find a working official Microsoft link to the RTF specification and add it here, you'll be remembered fondly.
 
-* [Swissmains Link to RTF Spec 1.9.1](https://manuals.swissmains.com/pages/viewpage.action?pageId=1376332&preview=%2F1376332%2F10620104%2FWord2007RTFSpec9.pdf)
 * [Webarchive Link to RTF Spec 1.9.1](https://web.archive.org/web/20190708132914/http://www.kleinlercher.at/tools/Windows_Protocols/Word2007RTFSpec9.pdf)
 * [RTF Extensions, MS-OXRTFEX](https://docs.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxrtfex/411d0d58-49f7-496c-b8c3-5859b045f6cf)

changelog.d/changelog_template.jinja

@@ -1,15 +1,15 @@
-{% if sections[""] %}
-{% for category, val in definitions.items() if category in sections[""] %}
-
-### {{ definitions[category]['name'] }}
-
-{% for text, values in sections[""][category].items() %}
-- {{ text }} {{ values|join(', ') }}
-{% endfor %}
-
-{% endfor %}
-{% else %}
-No significant changes.
-
-
-{% endif %}
+{% if sections[""] %}
+{% for category, val in definitions.items() if category in sections[""] %}
+
+### {{ definitions[category]['name'] }}
+
+{% for text, values in sections[""][category].items() %}
+- {{ text }} {{ values|join(', ') }}
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+
+{% endif %}