commit 5592439130d9a4f83f14ac7d92fdba24f091e48e
parent 563841de291762c24fa2b6ad09ad505ea3350590
Author: hhvn <dev@hhvn.uk>
Date: Sun, 12 Jun 2022 21:32:21 +0100
Create hirc.conf.5 and tweak some documentation
Diffstat:
5 files changed, 107 insertions(+), 31 deletions(-)
diff --git a/Makefile b/Makefile
@@ -25,6 +25,7 @@ SRC = src/main.c src/mem.c src/handle.c src/hist.c \
src/str.c src/params.c $(PARSE:.y=.c)
OBJ = $(SRC:.c=.o)
MAN = doc/hirc.1
+MAN5 = doc/hirc.conf.5
COMMIT = $(shell git log HEAD...HEAD~1 --pretty=format:%h)
CFLAGS = $(DEBUG)
LDFLAGS = -lncursesw
@@ -58,8 +59,8 @@ $(BIN): $(OBJ)
$(MAN): $(BIN) $(MAN).header $(MAN).footer
./$(BIN) -d | \
- cat $(MAN).header - $(MAN).footer | \
- sed "s/COMMIT/$(COMMIT)/" > $(MAN)
+ cat $(MAN).header - $(MAN).footer \
+ > $(MAN)
misc:
cd misc/ && make \
@@ -84,9 +85,12 @@ misc-clean:
install: all misc-install
mkdir -p $(BINDIR) $(MANDIR)/man1
install -m0755 $(BIN) $(BINDIR)/$(BIN)
- sed 's/COMMIT/$(COMMIT)/' \
+ sed "s/COMMIT/$(COMMIT)/" \
< $(MAN) \
> $(MANDIR)/man1/`basename $(MAN)`
+ sed "s/COMMIT/$(COMMIT)/" \
+ < $(MAN5) \
+ > $(MANDIR)/man5/`basename $(MAN5)`
uninstall: misc-uninstall
-rm -f $(BINDIR)/$(BIN)
diff --git a/doc/hirc.1.footer b/doc/hirc.1.footer
@@ -26,11 +26,23 @@ so that '/unalias /command` is translated to `/alias -delete /command`
.Dl /server hlircnet /ignore -E -server ^:[^ ]* (JOIN|PART|QUIT).*
Ignore join, part and quit messages on server 'hlircnet'.
+.Sh DISCLAIMER
+Since
+.Nm
+is purely a hobby project aiming to be:
+.Bl -dash -compact
+.It
+fun
+.It
+an IRC client tailoured to my liking.
+.El
+there are many features one may expect of IRC clients left missing,
+or handled in ways that are not 'proper'.
+Implement it yourself, or deal with it.
.Sh SEE ALSO
-.Bl -compact -tag -width "hirc2txt()"
-.It Xr irssi 1
-.It Xr irccat 1
-.It Xr hirc2txt 1
-Displays hirc logs in a human friendly way.
+.Xr hirc.conf 5 ,
+.Xr irccat 1 ,
+.Xr hirc2txt 1 ,
+.Xr irssi 1
.Sh AUTHOR
.An hhvn Aq Mt dev@hhvn.uk
diff --git a/doc/hirc.1.header b/doc/hirc.1.header
@@ -22,28 +22,11 @@ a lot of configurability and integrating some things only
possible with perl plugins. That said,
.Nm
does not share any code with irssi.
-.Sh DISCLAIMER
-Since
-.Nm
-is purely a hobby project aiming to be:
-.Bl -dash -compact
-.It
-fun
-.It
-an IRC client tailoured to my liking.
-.El
-there are many features one may expect of IRC clients left missing,
-or handled in ways that are not 'proper'.
-Implement it yourself, or deal with it.
-.Sh CONFIGURATION
-.Nm
-reads each line of
-.Ar configfile
-executing any that are begin with '/' as commands.
-Any line beginning with a character other than '/' are ignored.
-.Ss Formats
-Variables beginning with format.* are used to customize the way that messages and ui elements are formatted.
+See also
+.Xr hirc.conf 5
+for configuring hirc.
+.Ss Formats
Previously a custom parser was used, but now one generated by
.Xr yacc 1
is used. This means that formats are now checked for syntax errors on /set or /format,
diff --git a/doc/hirc.conf.5 b/doc/hirc.conf.5
@@ -0,0 +1,77 @@
+.\" vim: set syntax=nroff :
+.Dd COMMIT
+.Dt hirc.conf 5
+.Os
+.Sh NAME
+.Nm hirc.conf
+.Nd configuration format for
+.Xr hirc 1
+.Sh DESCRIPTION
+A
+.Nm
+file is made up of lines. Each line can be either a command or a comment.
+A command is a line that begins with a forward-slash
+.Pq Sq / :
+these are executed by hirc as though they were typed by the user.
+Any other line is a comment and results in no action.
+
+The commands that can be used in
+.Nm
+are described in
+.Xr hirc 1 .
+.Sh GENERATION
+See the
+.Ic dump
+command in
+.Xr hirc 1
+.Sh TIPS
+This section is entirely informative in intent and does not constitute a recommendation.
+.Ss Comments
+Comments can usually be written directly at the beginning of a line without worrying about inserting any special characters.
+In order to prevent a command from running, a space
+.Pq Sq \
+can be placed at the start of the line.
+It may be hard to tell wether a line is a comment or not with this,
+so using a hash
+.Pq Sq #
+instead may be preferred.
+Syntax highlighting can also be used,
+making it very easy to tell if a line is a comment or not, visually:
+see the
+.Sx FILES
+section.
+.Ss Running Multiple Commands
+With commands that take other commands as arguments (e,g:
+.Ic /alias
+and
+.Ic /bind )
+there is no syntax for passing multiple commands.
+
+However,
+.Nm
+can be used to create macros, that can then be called using the
+.Ic /source
+command.
+
+An example macro named
+.Pa ~/.config/hirc/macros/clutter :
+.Dl /toggle buflist.hidden
+.Dl /toggle nicklist.hidden
+
+Which could be configured to run on a keybind with:
+.Dl /bind ^[b /source ~/.config/hirc/macros/clutter
+.Sh FILES
+Files included with the hirc source repository:
+.Bl -tag -width vim/ftdetect/hirc.vim -compact
+.It Pa doc/example.conf
+Example configuration.
+.It Pa vim/syntax/hirc.vim
+Syntax file for
+.Xr vim 1 .
+.It Pa vim/ftdetect/hirc.vim
+Detection of hirc config files for
+.Xr vim 1 .
+.Sh SEE ALSO
+.Xr hirc 1
+.Sh AUTHOR
+.An hhvn Aq Mt dev@hhvn.uk
diff --git a/src/main.c b/src/main.c
@@ -87,7 +87,7 @@ main(int argc, char *argv[]) {
if (argc == 2 && strcmp(argv[1], "-d") == 0) {
printf(".Bl -tag\n");
for (i=0; config[i].name; i++) {
- printf(".It %s\n", config[i].name);
+ printf(".It Ic %s\n", config[i].name);
printf(".Bd -literal -compact\n");
printf("Default value: %s\n", config_get_pretty(&config[i], 1));
for (j=0; config[i].description[j]; j++)
@@ -98,7 +98,7 @@ main(int argc, char *argv[]) {
printf(".Sh COMMANDS\n");
printf(".Bl -tag\n");
for (i=0; commands[i].name && commands[i].func; i++) {
- printf(".It /%s\n", commands[i].name);
+ printf(".It Ic /%s\n", commands[i].name);
printf(".Bd -literal -compact\n");
for (j=0; commands[i].description[j]; j++)
printf("%s\n", commands[i].description[j]);
