Skip to content

Commit 4ad9013

Browse files
committed
docs: enhance concept documentation for clarity and conciseness
1 parent 1d7b94b commit 4ad9013

File tree

1 file changed

+35
-40
lines changed

1 file changed

+35
-40
lines changed

docs/docs/home/concept.md

Lines changed: 35 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -2,84 +2,79 @@
22

33
## Why TPPT?
44

5-
Even in the current era of widespread generative AI, there are still many requests for submitting reports in pptx format.
6-
(Are we the only ones being left behind?)
5+
In today's world where generative AI is becoming ubiquitous, many organizations still require reports to be submitted in PowerPoint (pptx) format.
6+
(Or is it just us who are being left behind?)
77

8-
TPPT is a wrapper for python-pptx that provides type-safe usage of slide masters and more.
8+
TPPT is a powerful wrapper for python-pptx that brings type safety to slide masters and more.
99

10-
It also incorporates ideas to make it easy to use and intuitive to write,
11-
hoping to make your pptx generation safer and simpler.
10+
We've designed it to be both intuitive and easy to use,
11+
making your PowerPoint generation process safer and more efficient.
1212

13-
## Reducing Imports
14-
Let's look at the Quick Start again:
13+
## Minimal Imports
14+
Let's revisit the Quick Start example:
1515
```python
1616
--8<-- "codes/quick_start.py"
1717
```
1818

19-
This code only imports TPPT.
19+
Notice how this code only requires a single import of TPPT.
2020

21-
You can create PowerPoint presentations with an extremely minimal number of imports.
21+
With just this minimal import, you can create complete PowerPoint presentations.
2222

23-
This is an experimental approach to increase the success rate of code generation by AI,
24-
by ensuring that only importing tppt is sufficient.
23+
This design choice is intentional - by requiring only the TPPT import,
24+
we aim to improve the success rate of AI-generated code.
2525

26-
Two techniques are used to achieve this:
26+
We achieve this through two key techniques:
2727

28-
### Active Adoption of Literal Types
29-
30-
For example, the shape of a Shape to be added to a slide can be written in the traditional way:
28+
### Simplified Unit Specification with Literals
3129

30+
Traditionally, specifying shape dimensions in PowerPoint would look like this:
3231
```python
3332
--8<-- "codes/quick_start_many_import.py"
3433
```
3534

36-
In other words, `tppt.types.Inches(1)` can be written as `(1, "in")`.
37-
38-
By expressing unit specifications with types using Literals in this way,
39-
we have reduced the imports that were previously necessary.
35+
With TPPT, you can write the same thing more concisely: `(1, "in")` instead of `tppt.types.Inches(1)`.
4036

41-
This is about writing; when reading properties, they are always converted to the Inches type,
42-
allowing for addition, subtraction, and comparison.
37+
This Literal-based approach significantly reduces the number of imports needed.
4338

44-
### Type Extraction
39+
While writing values is simplified, reading properties still gives you proper Inches objects,
40+
allowing you to perform arithmetic operations and comparisons as needed.
4541

46-
There are places where lambda expressions like `lambda slide: slide...` are used.
47-
This is lazy evaluation, where the type is extracted at the time of element initialization,
48-
and the element is completed by adding operations to it.
42+
### Smart Type Extraction
4943

50-
The characteristic of this approach is that instead of importing types and passing them to function arguments,
51-
types are extracted from within the function and used.
44+
You'll notice places where we use lambda expressions like `lambda slide: slide...`.
45+
This is a form of lazy evaluation - we extract the type at initialization time
46+
and then build the element by applying operations to it.
5247

53-
This further reduces imports for code generation.
48+
The beauty of this approach is that instead of importing types and passing them as function arguments,
49+
we extract and use types directly from within the function.
5450

55-
This method has another advantage.
56-
By extracting operations on the extracted types into functions,
57-
it becomes easier to share components.
51+
This not only reduces imports but also brings another advantage:
52+
by extracting type operations into functions, you can easily create reusable components.
5853

5954
```python
6055
--8<-- "codes/apply_sample.py"
6156
```
6257

63-
You can create your own modifier functions like `format_text` and easily reuse them.
58+
You can create and reuse your own formatting functions like `format_text` with ease.
6459

65-
### Type Safety
66-
This tool is mainly targeted at users who create new slides based on slide masters.
60+
### Type Safety First
61+
TPPT is designed primarily for users who create new slides based on slide masters.
6762

68-
If you're like me, you've probably struggled with giving types to python-pptx's slide masters.
63+
If you've worked with python-pptx before, you know the struggle of adding type safety to slide masters.
6964

70-
TPPT allows you to give types to slide masters using declarative type hints like pydantic.
65+
TPPT solves this by allowing you to define types for slide masters using pydantic-like declarative type hints:
7166

7267
```python
7368
--8<-- "codes/custom_slide_master.py"
7469
```
7570

76-
Is writing type definitions yourself tedious? We've prepared a modest tool for you.
71+
Don't want to write type definitions manually? We've got you covered with a handy tool:
7772

7873
```bash
7974
python -m tppt.tool.ppt2template $YOUR_TEMPLATE.pptx -o $OUTPUT_FILE.py
8075
```
8176

82-
After setting placeholders in the slide layout constructor,
83-
you can describe data such as text, pictures, and tables.
77+
After setting up placeholders in your slide layout constructor,
78+
you can easily add text, pictures, tables, and other elements.
8479

85-
All these operations are type-safe!
80+
And the best part? All these operations are fully type-safe!

0 commit comments

Comments
 (0)