Fossil SCM

fossil-scm / tools / fossil-makeinfo
Blame History Raw 522 lines
1
#!/usr/bin/env bash
2
# v0.1 Quick and dirty script to grab fossil's help and stuff it into a file.
3
# v0.2 Now I have working sed expressions, I can grab the help keywords.
4
# v0.3 This gets me the keywords and only the keywords.
5
# v0.4 Glue all relevant things together and produce an info file.
6
# v0.5 Working out sed/head/tail differences between GNU and BSD.
7
# v0.6 Replaced "head -n -1" with "sed '$d'" which does the same thing.
8
# v0.7 Adding help in separately for normal/auxil commands.
9
# v0.8 Added common options and Features. Got rid of some obvious bugs.
10
# v0.9 Added @bye at end.
11
# v0.10 Retitled Features to Fossil.
12
# v0.11 Added entries relevant to system-wide dir entry.
13
# v0.12 Reworded section introductions.
14
# v0.13 Added testing commands to texi output.
15
# v0.14 Added web commands to texi output. Note added far later.
16
# v0.15 Added Fossil settings.
17
# Builds a correct texinfo file (finally) on OpenBSD and NetBSD.
18
#
19
# Requires fossil, tail, GNU sed and makeinfo
20
#
21
22
##### Header #####
23
# put header, then common node, finish menu, then uncommon node then finish menu
24
echo "Create Header"
25
printf "\\input texinfo
26
@settitle Fossil
27
@setfilename fossil.info
28
@c @author brickviking
29
@dircategory Development
30
@direntry
31
* Fossil: (fossil). A distributed version control system.
32
@end direntry
33
34
" > fossil.texi
35
printf "@c Initial rendition to convert fossil help -a -v into texinfo for further
36
@c massaging by makeinfo. Scripts to do this automatically may come
37
@c later. Don't expect this to conform to GNU guidelines.
38
39
" >> fossil.texi
40
41
# Add a title page
42
printf "@titlepage
43
@title Fossil
44
@subtitle The Fossil Source Code Manager (fossil-scm)
45
@subtitle A distributed version control system
46
@author The fossil committers
47
48
@page
49
@vskip 0pt plus 1filll
50
51
@end titlepage
52
53
" >> fossil.texi
54
55
# Add @contents
56
printf "@contents\n
57
58
" >> fossil.texi
59
60
# Check fossil version. Only thing wrong with this is which fossil binary is picked up first.
61
# Older versions of fossil didn't have a version number, just a truncated commit hash.
62
fossil version | sed 's/This is fossil version /@set VERSION /' | cut -c1-17 >> fossil.texi
63
64
# Insert repeat of Top node for PDF. We have to hack to do this
65
printf "@ifnotinfo
66
@ifnothtml
67
@node Introduction
68
@top Introduction for Fossil - a distributed version control system
69
70
Fossil is a distributed version control system (DVCS) with built-in
71
forum, wiki, ticket tracker, CGI/HTTP interface, and HTTP server.
72
This file documents version @value{VERSION} of Fossil.
73
74
@end ifnothtml
75
@end ifnotinfo
76
" >> fossil.texi
77
78
printf "@node Top
79
@chapter Fossil
80
81
Fossil is a distributed version control system (DVCS) with built-in
82
forum, wiki, ticket tracker, CGI/HTTP interface, and HTTP server.
83
This file documents version @value{VERSION} of Fossil.
84
85
@c @node menu
86
@menu
87
* Introduction:: Introduction and features listed from the website front page.
88
* Common commands:: These are the commands that are most likely to be used.
89
* Uncommon commands:: These aren't used as often, but they're still there when needed.
90
* Test commands:: These are definitely not recommended for production use.
91
* Fossil settings:: These describe fossil settings.
92
* Web commands:: Available webpage help.
93
* Common arguments:: Arguments common to all commands.
94
* License:: The license agreement of the fossil project.
95
@end menu
96
97
You can get help for any of the available fossil commands by using:
98
99
@example
100
fossil help some-command
101
@end example
102
103
This will show you help on some-command. I've attempted to put all the available
104
help nodes from fossil into here, but it's vaguely possible I've missed some.
105
106
" >> fossil.texi
107
108
# Add in the Features from the front webpage
109
printf "@node Introduction,Common commands,Top,Top
110
@chapter Introduction
111
112
Fossil is a distributed version control system (DVCS) with built-in
113
forum, wiki, ticket tracker, CGI/HTTP interface, and HTTP server.
114
This file documents version @value{VERSION} of Fossil.
115
116
This is a quick breakdown of the things that you get when you run the fossil binary:
117
118
@enumerate
119
@item
120
Integrated Bug Tracking, Wiki, Forum, and Technotes
121
- In addition to doing distributed version control like Git and Mercurial, Fossil also supports bug tracking, wiki, forum, and tech-notes.
122
123
@item
124
Built-in Web Interface
125
- Fossil has a built-in and intuitive web interface that promotes project situational awareness. Type \"fossil ui\" and Fossil automatically opens a web browser to a page that shows detailed graphical history and status information on that project.
126
127
@item
128
Self-Contained
129
- Fossil is a single self-contained stand-alone executable. To install, simply download a precompiled binary for Linux, Mac, OpenBSD, or Windows and put it on your \$PATH. Easy-to-compile source code is available for users on other platforms.
130
131
@item
132
Simple Networking
133
- No custom protocols or TCP ports. Fossil uses plain old HTTP (or HTTPS or SSH) for all network communications, so it works fine from behind restrictive firewalls, including proxies. The protocol is bandwidth efficient to the point that Fossil can be used comfortably over dial-up or over the exceedingly slow Wifi on airliners.
134
135
@item
136
CGI/SCGI Enabled
137
- No server is required, but if you want to set one up, Fossil supports four easy server configurations.
138
139
@item
140
Autosync
141
- Fossil supports \"autosync\" mode which helps to keep projects moving forward by reducing the amount of needless forking and merging often associated with distributed projects.
142
143
@item
144
Robust & Reliable
145
- Fossil stores content using an enduring file format in an SQLite database so that transactions are atomic even if interrupted by a power loss or system crash. Automatic self-checks verify that all aspects of the repository are consistent prior to each commit.
146
147
@item
148
Free and Open-Source
149
- Uses the 2-clause BSD license.
150
@end enumerate
151
" >> fossil.texi
152
153
###### Common commands
154
echo "List common commands"
155
156
printf "@node Common commands,Uncommon commands,Introduction,Top
157
@chapter Common commands
158
159
These are the more commonly used commands for the average fossil user. They're
160
listed by fossil when you run the command:
161
162
@example
163
fossil help
164
@end example
165
166
They are similar to commands that are available in other VCS programs such as
167
subversion, git or mercurial.
168
169
" >> fossil.texi
170
171
# begin menu for common keywords
172
printf "@menu\n" >> fossil.texi
173
174
# Slurp in Common keywords from fossil help
175
# WARNING: tail count is brittle
176
echo "Grab common keywords for menu"
177
for u in $(for t in $(fossil help | tail -n +11| sed '$d'); do echo "$t"; done | sort); do echo "* ${u}::"; done >> fossil.texi
178
179
# Add end menu, add some space too
180
printf "@end menu
181
182
" >> fossil.texi
183
184
# Add in the actual help for common commands
185
# WARNING: tail count is brittle
186
# tail command pops off the first fourteen lines, sed commands remove the last two lines.
187
echo "Fossil output common help to workfile"
188
189
# I'd like if this could start at where the "Options:" is, and finish at the next
190
# pair of blank lines.
191
#printf "@table @option
192
#
193
#" >> fossil.texi
194
195
fossil help -v | tail -n +14 | sed '$d' | sed '$d' >workfile
196
197
# swap out @ with @@ so texinfo doesn't barf
198
echo "Doubling up the @'s"
199
sed -i -e 's/@/@@/g' workfile
200
201
echo "Swapping out # for @node ... \n@section ..."
202
# This swaps out "# keyword" with
203
# @node keyword
204
# @section keyword
205
# breaks on *BSD's seds, needs gsed there
206
207
# Check the OS so we can use gsed if needed
208
MYOS="$(uname )"
209
if [[ ${MYOS} == "Linux" ]]; then
210
sed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
211
else
212
# We'll assume we're on a BSD here, even though this won't always be true
213
gsed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
214
fi
215
216
# turns --switches into @option{--switches}
217
sed -i -e 's/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' workfile
218
# now do the same for places where there's -f|--force
219
sed -i -e 's/|--\([[:alnum:]-]\{1,\}\)/|@option\{--\1\}/g' workfile
220
# turns -switches into @option{-switches}. Usually starts with space
221
sed -i -e 's/ -\([[:alnum:]-]\{1,\}\)/ @option\{-\1\}/g' workfile
222
# ... and adds it to the output file with some space
223
cat workfile >> fossil.texi
224
225
##### Uncommon commands ####
226
echo "List uncommon commands"
227
printf "
228
@node Uncommon commands,Test commands,Common commands,Top
229
@chapter Uncommon commands
230
231
These are auxiliary commands, listed by fossil when you run the command:
232
233
@example
234
fossil help -x
235
@end example
236
237
They're not used quite as often, and are normally used in specific
238
circumstances, such as creating fossils suitable for hosting.
239
240
@menu
241
" >> fossil.texi
242
243
# Slurp in auxiliary/uncommon keywords - no need to remove last line here
244
echo "Grab uncommon keywords for menu"
245
for u in $(for t in $(fossil help -x); do echo "$t"; done | sort); do echo "* ${u}::"; done >> fossil.texi
246
247
echo "@end menu" >> fossil.texi
248
echo "" >> fossil.texi
249
250
# Now add all the help from "fossil help -x -v"
251
# WARNING: tail count is brittle
252
# sed comands remove the last two lines.
253
echo "Fossil output auxiliary help to workfile"
254
fossil help -x -v | tail -n +4 | sed '$d' | sed '$d' >workfile
255
256
# swap out @ with @@ so texinfo doesn't barf
257
echo "Doubling up the @'s"
258
sed -i -e 's/@/@@/g' workfile
259
260
# This swaps out "# keyword" with
261
# @node keyword
262
# @unnumbered keyword
263
# breaks on *BSD's seds, needs gsed there
264
echo "Swapping out # for @node ... \n@unnumbered ..."
265
266
if [[ ${MYOS} == "Linux" ]]; then
267
sed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
268
else
269
# We'll assume we're on a BSD here, even though this won't always be true
270
gsed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
271
fi
272
273
# turns --switches into @option{--switches}
274
sed -i -e 's/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' workfile
275
276
# ... and adds it to the output file with a spacer line
277
cat workfile >> fossil.texi
278
echo "" >> fossil.texi
279
280
##### Now the test commands. Here be dragons. #####
281
echo "List test commands"
282
printf "@node Test commands,Fossil settings,Uncommon commands,Top
283
@chapter Testing commands
284
285
These are testing commands, listed by fossil when you run the command:
286
287
@example
288
fossil help -t
289
@end example
290
291
They're often used to solve specific little problems that didn't warrant a full
292
tool, but are useful enough to be kept around. They are most definitely not
293
supported, and the developers will expect to change these far more often. They
294
are not stable, so do not depend upon their behavior, or even their existence.
295
296
@menu\n" >> fossil.texi
297
298
# Insert test commands in here
299
echo "Grab test keywords for menu"
300
for u in $(for t in $(fossil help -t); do echo "$t"; done | sort); do echo "* ${u}::"; done >> fossil.texi
301
302
# Now end that menu (Test commands)
303
echo "@end menu
304
305
" >> fossil.texi
306
307
# Now add all the help from "fossil help -t -v"
308
# WARNING: tail count is brittle
309
# sed comands remove the last two lines.
310
echo "Fossil output test help to workfile"
311
fossil help -t -v | tail -n +4 | sed '$d' | sed '$d' >workfile
312
313
# swap out @ with @@ so texinfo doesn't barf
314
echo "Doubling up the @'s"
315
sed -i -e 's/@/@@/g' workfile
316
317
# This swaps out "# keyword" with
318
# @node keyword
319
# @unnumbered keyword
320
# breaks on *BSD's seds, needs gsed there
321
echo "Swapping out # for @node ... \n@unnumbered ..."
322
323
if [[ ${MYOS} == "Linux" ]]; then
324
sed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
325
else
326
# We'll assume we're on a BSD here, even though this won't always be true
327
gsed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
328
fi
329
330
# turns --switches into @option{--switches}
331
sed -i -e 's/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' workfile
332
333
# ... and adds it to the output file with a spacer line
334
cat workfile >> fossil.texi
335
echo "" >> fossil.texi
336
337
##### Now, add in fossil settings #####
338
# The usual wyvern warnings.
339
echo "List settings"
340
printf "@node Fossil settings,Web commands,Test commands,Top
341
@chapter Fossil settings
342
343
These are help pages for settings within fossil, shown when you run:
344
@example
345
fossil help -s
346
@end example
347
348
@menu\n" >> fossil.texi
349
350
# Insert settings keywords in here
351
echo "Grab settings keywords for menu"
352
for u in $(for t in $(fossil help -s); do echo "$t"; done | sort); do echo "* ${u}::"; done >> fossil.texi
353
354
# and finish the menu
355
echo "@end menu
356
357
" >> fossil.texi
358
# Now add all the help from "fossil help -s -v"
359
# WARNING: tail count is brittle
360
# sed comands remove the last two lines.
361
echo "Fossil output test help to workfile"
362
fossil help -s -v | tail -n +4 | sed '$d' | sed '$d' >workfile
363
364
# swap out @ with @@ so texinfo doesn't barf
365
echo "Doubling up the @'s"
366
sed -i -e 's/@/@@/g' workfile
367
368
# This swaps out "# keyword" with
369
# @node keyword
370
# @unnumbered keyword
371
# breaks on *BSD's seds, needs gsed there
372
echo "Swapping out # for @node ... \n@unnumbered ..."
373
374
if [[ ${MYOS} == "Linux" ]]; then
375
sed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
376
else
377
# We'll assume we're on a BSD here, even though this won't always be true
378
gsed -i -e 's/^##* \([a-z0-9-]\{1,\}\)/@node \1\n@section \1\n/' workfile
379
fi
380
381
# This has to be done before swapping --switches because the next command
382
# adds @option(--switches} and hence reuses the {}.
383
echo "Swapping out {} for @{ @}"
384
# swaps out {} for @{ @}
385
if [[ ${MYOS} == "Linux" ]]; then
386
sed -i -e 's/{/@{/g' -e 's/}/@}/g' workfile
387
else
388
gsed -i -e 's/{/@{/g' -e 's/}/@}/g' workfile
389
fi
390
391
# turns --switches into @option{--switches}
392
sed -i -e 's/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' workfile
393
394
# ... and adds it to the output file with a spacer line
395
cat workfile >> fossil.texi
396
echo "" >> fossil.texi
397
398
# Now the webpage content. Here be wild wild web pages.
399
echo "List web commands"
400
printf "@node Web commands,Common arguments,Fossil settings,Top
401
@chapter Web commands
402
403
These are help pages for the internal web pages, listed by fossil when you run the command:
404
405
@example
406
fossil help -w
407
@end example
408
409
All of these can be provided to the URL line on the browser address input like the
410
example below, that starts from the final / (in this case, /timeline?ms=glob):
411
412
@example
413
https://fossil.example.com/fossil/timeline?ms=glob
414
@end example
415
416
@menu\n" >> fossil.texi
417
418
# Insert webpage keywords in here
419
echo "Grab web keywords for menu"
420
for u in $(for t in $(fossil help -w); do echo "$t"; done | sort); do echo "* ${u}::"; done >> fossil.texi
421
422
423
# Now end that menu (Webpages)
424
echo "@end menu
425
426
" >> fossil.texi
427
428
# Now add all the help from "fossil help -w -v"
429
# WARNING: tail count is brittle
430
# sed comands remove the last two lines.
431
echo "Fossil output webpage help to workfile"
432
fossil help -w -v | tail -n +4 | sed '$d' | sed '$d' >workfile
433
434
# swap out @ with @@ so texinfo doesn't barf
435
echo "Doubling up the @'s"
436
sed -i -e 's/@/@@/g' workfile
437
438
# This swaps out "# keyword" with
439
# @node keyword
440
# @unnumbered keyword
441
# breaks on *BSD's seds, needs gsed there
442
echo "Swapping out # for @node ... \n@unnumbered ..."
443
444
if [[ ${MYOS} == "Linux" ]]; then
445
# use a different separator here, as we need to keep /_. in strings
446
sed -i -e 's%^##* /\([_.a-z0-9-]\{1,\}\)%@node /\1\n@section /\1\n%' workfile
447
else
448
# We'll assume we're on a BSD here, even though this won't always be true
449
gsed -i -e 's%^##* /\([_.a-z0-9-]\{1,\}\)%@node /\1\n@section /\1\n%' workfile
450
fi
451
452
# This has to be done before swapping --switches because the next command
453
# adds @option(--switches} and hence reuses the {}.
454
echo "Swapping out {} for @{ @}"
455
# swaps out {} for @{ @}
456
if [[ ${MYOS} == "Linux" ]]; then
457
sed -i -e 's/{/@{/g' -e 's/}/@}/g' workfile
458
else
459
gsed -i -e 's/{/@{/g' -e 's/}/@}/g' workfile
460
fi
461
462
echo "Swapping out --switches for @option{--switches}"
463
# turns --switches into @option{--switches}
464
if [[ ${MYOS} == "Linux" ]]; then
465
sed -i -e 's/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' workfile
466
else
467
gsed -i -e 's/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' workfile
468
fi
469
470
# ... and adds it to the output file with a spacer line
471
cat workfile >> fossil.texi
472
echo "" >> fossil.texi
473
474
# Add in common args
475
echo "List common args"
476
echo "@node Common arguments,License,Web commands,Top
477
@chapter Common arguments
478
479
These are commandline arguments that are common to all fossil commands.
480
481
" >> fossil.texi
482
483
# Slurp in auxiliary/uncommon keywords
484
echo "Grab common args text"
485
# At the moment, this doesn't do lines, and also requires GNU sed
486
if [[ ${MYOS} == "Linux" ]]; then
487
fossil help -o | sed -e '2,$s/^ /\n/' -e '2,$s/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' >> fossil.texi
488
else
489
fossil help -o | gsed -e '2,$s/^ /\n/' -e '2,$s/--\([[:alnum:]-]\{1,\}\)/@option\{--\1\}/g' >> fossil.texi
490
fi
491
# stray stuff that didn't work
492
# sed -e '/--/s/--\(.*\s+\)/@item --\1 /' >> fossil.texi
493
echo "" >> fossil.texi
494
495
# Add in licence. Look for it in two places, just in case we're in tools/ when
496
# we call this program.
497
if [[ -f COPYRIGHT-BSD2.txt ]]; then
498
HERE="COPYRIGHT-BSD2.txt"
499
elif [[ -f ../COPYRIGHT-BSD2.txt ]]; then
500
HERE="../COPYRIGHT-BSD2.txt"
501
else
502
echo "Where's COPYRIGHT-BSD2.txt?"
503
fi
504
# TODO: This should fail if we couldn't find COPYRIGHT-BSD2.txt
505
printf "
506
@node License,,Common arguments,Top
507
@chapter License agreement
508
509
@include ${HERE}
510
511
" >> fossil.texi
512
513
# Every good thing has to end
514
echo "@bye" >> fossil.texi
515
516
# and now we make the final info file - commented out for now
517
# makeinfo fossil.texi
518
519
echo "Done ... for now. Please check fossil.texi file over for inconsistencies, and fill in descriptions."
520
echo "Once everything's good, you can run your system's makeinfo command to turn"
521
echo "your .texi file into a .info file to install where you need."
522

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button