Skip to content

Commit 03bfc36

Browse files
striezelstriezel
committed
documentation: explain basic usage of program
1 parent b02ee1f commit 03bfc36

File tree

3 files changed

+132
-0
lines changed

3 files changed

+132
-0
lines changed

‎documentation/SUMMARY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
[Installation](installation.md)
66

7+
[Using pmdb](basic_usage.md)
8+
79
[Location of pmdb's files](directories.md)
810

911
[Templates](templates.md)

‎documentation/basic_usage.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Using pmdb
2+
3+
After the [installation](installation.md) is done, you can start using `pmdb`.
4+
For that you need private messages from a vBulletin forum, download in XML
5+
format. vBulletin offers options to download all private messages as XML, CSV or
6+
text, but `pmdb` can only use the XML format, not text or CSV. Use XML only.
7+
Usually all private messages can be downloaded via a link like
8+
`https://www.example.com/forum/private.php?do=downloadpm&dowhat=xml`, adjust
9+
accordingly for your case.
10+
11+
## Importing messages from XML
12+
13+
Assuming the XML file was downloaded as `privatemessages-Name-31.12.2024.xml` to
14+
the current directory, you can let `pmdb` process the file by typing
15+
16+
```sh
17+
pmdb --xml privatemessages-Name-31.12.2024.xml
18+
```
19+
20+
Doing so will display something like
21+
22+
```
23+
XML file "privatemessages-Name-31.12.2024.xml" was queued for loading.
24+
Import of private messages from privatemessages-Name-31.12.2024.xml was successful.
25+
321 PMs read, new PMs: 321
26+
PMs in the database: 321
27+
Messages saved successfully.
28+
Folder map saved successfully.
29+
```
30+
31+
`pmdb` tells you that it imported the private messages ("PMs") successfully, and
32+
how many messages were read - in that case 312 messages. It also saves the
33+
imported messages to its [data directory](directories.md) for later use.
34+
35+
You can add more messages at a later point by adding more XML files. Or you can
36+
also let `pmdb` process several XML files at once. Just repeat the `--xml`
37+
paramater and add another file name. For example,
38+
39+
```sh
40+
pmdb --xml privatemessages-Name-31.12.2024.xml --xml other/directory/privatemessages-Name-28.02.2025.xml
41+
```
42+
43+
will process both `privatemessages-Name-31.12.2024.xml` and
44+
`other/directory/privatemessages-Name-28.02.2025.xml` and import messages from
45+
those files. In that case the program's output could look like
46+
47+
```
48+
XML file "privatemessages-Name-31.12.2024.xml" was queued for loading.
49+
XML file "other/directory/privatemessages-Name-28.02.2025.xml" was queued for loading.
50+
Import of private messages from privatemessages-Name-31.12.2024.xml was successful.
51+
321 PMs read, new PMs: 321
52+
Import of private messages from other/directory/privatemessages-Name-28.02.2025.xml was successful.
53+
345 PMs read, new PMs: 24
54+
PMs in the database: 345
55+
Messages saved successfully.
56+
Folder map saved successfully.
57+
```
58+
59+
If two files contain the same messages, `pmdb` will recognize this and not add
60+
the same message twice. It basically does automatic deduplication on import, so
61+
you don't have to worry about overlapping messages in the XML files.
62+
63+
## Generate HTML files
64+
65+
OK, so now that we have imported those messages, how can we actually view them?
66+
That's where HTML generation steps in. `pmdb` will generate HTML files for each
67+
message so that you can then view them in a browser. Just type
68+
69+
```sh
70+
pmdb --html
71+
```
72+
73+
and `pmdb` does the rest. It will print something like
74+
75+
```
76+
Loading messages from /home/name/.pmdb/messages/ ...
77+
All messages from /home/name/.pmdb/messages/ loaded. Read: 345; new: 345
78+
Loaded folder map from /home/name/.pmdb/messages/, too.
79+
PMs in the database: 345
80+
Messages saved successfully.
81+
Folder map saved successfully.
82+
Loading pmdb.conf was successful.
83+
Creating HTML files for message texts. This may take a while...
84+
All HTML files were created successfully!
85+
Opening /home/name/.pmdb/html/folder_94835ea2fcf775cd77cb9c9cee01b5cbd9bc515467aab1215f48a5ade9ca5274.html in browser ...
86+
```
87+
88+
It will then open the generated file in a browser, for example Firefox or
89+
Chromium. There you can browse through the messages as if they were in the
90+
forum.
91+
92+
## Doing it all in one go
93+
94+
Of course, you can import message data in one step and then generate the HTML
95+
files to view in a second step, but `pmdb` also can do that in one go. Staying
96+
with the file names from above, you could just type
97+
98+
```sh
99+
pmdb --xml privatemessages-Name-31.12.2024.xml --xml other/directory/privatemessages-Name-28.02.2025.xml --html
100+
```
101+
102+
to import both XML files and generate the corresponding HTML files in one step.
103+
In that case, assuming no messages have been imported so far, the output of
104+
`pmdb` could be:
105+
106+
```
107+
XML file "privatemessages-Name-31.12.2024.xml" was queued for loading.
108+
XML file "other/directory/privatemessages-Name-28.02.2025.xml" was queued for loading.
109+
Import of private messages from privatemessages-Name-31.12.2024.xml was successful.
110+
321 PMs read, new PMs: 321
111+
Import of private messages from other/directory/privatemessages-Name-28.02.2025.xml was successful.
112+
345 PMs read, new PMs: 24
113+
PMs in the database: 345
114+
Messages saved successfully.
115+
Folder map saved successfully.
116+
Loading pmdb.conf was successful.
117+
Creating HTML files for message texts. This may take a while...
118+
All HTML files were created successfully!
119+
Opening /home/name/.pmdb/html/folder_94835ea2fcf775cd77cb9c9cee01b5cbd9bc515467aab1215f48a5ade9ca5274.html in browser ...
120+
```
121+
122+
And `pmdb` will then open the generated HTML file in the browser.
123+
124+
In general, `pmdb` will let you combine paramaters and tasks freely most of the
125+
time. (There are some exceptions like the `--help` or `--version` parameters
126+
which will just print the information and then exit.)

‎documentation/installation.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,3 +60,7 @@ to test this on.
6060

6161
If you need ton run pmdb on macOS, you can either try to compile from source or
6262
you could try to run the Windows binaries with the [Wine compatibility layer](https://www.winehq.org/).
63+
64+
---
65+
66+
Let's move on to the [basics of how to use pmdb](basic_usage.md).

0 commit comments

Comments
 (0)