~brettgilio/org-webring

ref: 77a6133248197a83f54d8c132c6f91d620bc3820 org-webring/docs/README.org -rw-r--r-- 6.9 KiB
77a61332 — Brett Gilio Create a variable for the attribution prefix text. 10 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
#+title: org-webring
#+options: toc:nil
#+export_file_name: ../README.md

* org-webring
Static RSS/ATOM webring generator for org-mode

~org-webring~ is an alternative implementation of a feed-based
webring, taking inspiration from ~openring~ by Drew DeVault.
Intended to integrate with Org-based websites and blogs (either
directly, or indirectly, as in ox-hugo), it will fetch a given list
of web-feed files and correctly parse and format the elements to be
displayed for sharing.

** Usage & Documentation
The CSS file ~org-webring.css~ needs to be loaded by your website,
and your browser must be able to render flex boxes. This file
provides stylization support for both the ~webring~ and ~planet~
functionality.

The files ~ring.org~ and ~planet.org~ are templates. Copy one
or both of them into a specified directory from where your website
is generated. Add all relevant web-feed URLs to ~org-webring-urls~
for fetching, and adjust variables as desired.

To include the results of ~ring.org~ into an Org file export of
your choosing, simply add: "#+INCLUDE: ./ring.org", taking care to
modify the path appropriately.  When you regenerate your Org-based
(or Hugo, using ox-hugo) website, the function
~org-webring-generate-webring~ will be evaluated and the result
will be displayed.

The file ~reply.org~ is a mock demonstration, utilizing post-pinning,
to emulate a scenario where you would emphasize another blogger's post
and supplement it with a response of your own.

Additionally, if you are using the ~planet.org~ file, simply have
the ~org-publish~ functionality of your choosing convert the file
to HTML and serve it as you would any other page. This page is
designated standalone, and probably should not be included in
other Org-mode files. The result is produced by the
~org-webring-generate-planet~ function.

*** *Variable*: org-webring-items-total
The total number of items displayed on the webring.
- Type: =Integer=
- Default Value: ~3~

*** *Variable*: org-webring-items-per-source
The number of entries extracted from each source.
- Type: =Integer=
- Default Value: ~1~

*** *Variable*: org-webring-header
The default text displayed in the header.
- Type: =String=
- Default Value: ~"Posts from other blogs I follow..."~

*** *Variable*: org-webring-display-header
Display the result of ~org-webring-header~.

When set to ~non-NIL~, the generator will display the value
set for the header.
- Type: =Bool=
- Default Value: ~t~

*** *Variable*: org-webring-urls
The source URLs which are scraped for feeds.
- Type: =List-of-strings=
- Default Value: ~'()~

*** *Variable*: org-webring-summary-max-length
The maximum number of characters displayed in the summary field.

When ~NIL~, no summary will be displayed.
- Type: =Sexp=
- Default Value: ~512~

*** *Variable*: org-webring-timestamp-feed-format
The string format used for the publication dates of feed items.

This variable uses the same '%'-sequences as ~format-time-string~.
- Type: =String=
- Default Value: ~"%a, %d %b %Y"~

*** *Variable*: org-webring-timestamp-generate-format
The string format used for the generation of the webring or planet.

This variable uses the same '%'-sequences as ~format-time-string~.
- Type: =String=
- Default Value: ~"%a, %d %b %Y — %R"~

*** *Variable*: org-webring-display-generation-time
Display the result of ~org-webring-timestamp-generate-format~.

When set to ~non-NIL~, the generator will display the most
recent generation time of ~org-webring~.
- Type: =Bool=
- Default Value: ~t~

*** *Variable*: org-webring-display-attribution
Display the software attribution under the webring or planet.

When set to ~non-NIL~, the generator will display the name of
the program used to generate the webring or planet.
- Type: =Bool=
- Default Value: ~t~

*** *Variable*: org-webring-attribution-prefix
Text which will be displayed before the attribution.
- Type: =String=
- Default Value: ~Generated with~

*** *Variable*: org-webring-display-version
Display the current version of ~org-webring~.

When set to ~non-NIL~, the generator will display the current
version of ~org-webring~.
- Type: =Bool=
- Default Value: ~t~
  
*** *Variable*: org-webring-empty-summary
Text which will replace a summary with an empty string.
- Type: =String=
- Default Value: ~"No summary available."~

*** *Variable*: org-webring-pinned-posts
A list of feed item URLs that should be pinned.

This is not supported by ~planet~.
- Type: =List-of-strings=
- Default Value: ~'()~

*** *Variable*: org-webring-pin-symbol
The symbol used to denote a pinned item.
- Type: =String=
- Default Value: ~🖈~

*** *Variable*: org-webring-filtered-posts
A list of feed item URLs that should be filtered.

This is supported by both ~webring~ and ~planet~.
- Type: =List-of-strings=
- Default Value: ~'()~

*** *Variable*: org-webring-planet-items-total
The total number of items generated by the planet.
- Type: =Integer=
- Default Value: 50

*** *Variable*: org-webring-planet-display-description
Display the planet description.

When set to ~non-NIL~, the generator will display the value
set for the planet description.
- Type: =Bool=
- Default Value: ~t~

*** *Variable*: org-webring-planet-description
Text of the planet description.
- Type: =String=
- Default Value: ~"Default planet description."~

*** *Variable*: org-webring-planet-syndicate-length
The maximum length of all syndicate titles.
- Type: =String=
- Default Value: ~25~

*** *Variable*: org-webring-override-time-locale
A convenient way to override the time encoding.

Your selected locale must be available on your machine, otherwise no
effect will be witnessed.
- Type: =String=
- Default Value: ~env LANG~

*** *Function*: org-webring-generate-webring
Generate the entire webring and return it as HTML.

*** *Function*: org-webring-generate-planet
Generate the entire planet with syndicates list and return it
as HTML.

*** *Function*: org-webring-version
Display the current version of ~org-webring~ in the echo area.

** Installation
- You may checkout the git repository and add the directory to your GNU Emacs loadpath.

or

- You may use GNU Guix, either from the repository or by using the script available in our =/etc= directory.

** Resources
   Source code at [[https://git.sr.ht/~brettgilio/org-webring][~brettgilio/org-webring]].

   [[https://git-send-email.io][Send patches]] and questions to [[https://lists.sr.ht/~brettgilio/org-webring][~brettgilio/org-webring@lists.sr.ht]].

   Issue tracker at [[https://todo.sr.ht/~brettgilio/org-webring][~brettgilio/org-webring]].


** License
=org-webring= is licensed under the =GNU General Public License, version 3=
or any later version. See [[./LICENSE][LICENSE]] for more details.

#+NAME: license
#+begin_export html
 <img src="https://e.brettgilio.com/gplv3.svg" alt="GPL" width="155" height="64">
#+end_export


* COMMENT Local variables
# Local Variables:
# eval: (setq org-html-text-markup-alist '((strike-through . "~~%s~~")))
# eval: (add-hook 'after-save-hook #'org-md-export-to-markdown nil t)
# End: