breezewiki-docs/docs.scrbl

#lang scribble/base

@(require scribble/manual)
@(define (code . pre-content) (elem (apply literal pre-content) #:style 'tt))

@title{BreezeWiki Documentation}

@url{https://breezewiki.com}

@local-table-of-contents[]

@; -----------------------------------------------------------------------------

@section{Links}

@itemlist[
@item{Source code: @url{https://gitdab.com/cadence/breezewiki}}
@item{How to bug report or feature request: @Secref["Reporting Bugs"]}
@item{Planned features: <TODO>}
@item{Community: @url{https://matrix.to/#/#breezewiki:cadence.moe}}
]

@; -----------------------------------------------------------------------------

@section[#:tag "Reporting Bugs"]{Reporting Bugs}

Bug reports are important, and so are feature requests! Thank you for your interest. Here's how to send in yours.

There is the @italic{mailing list} which is the first line for people like you to report to. Once a bug is confirmed, I will copy it onto the @italic{todo tracker} as a task item.

Please spend one minute checking the todo tracker so you don't submit a duplicate of somebody else's report.

For real-time chat with the community, check out @url{https://matrix.to/#/#breezewiki:cadence.moe}.

@subsection{Actually sending a report}

To actually send in your report, compose an email to @hyperlink["mailto:~cadence/breezewiki-discuss@lists.sr.ht" "~cadence/breezewiki-discuss@lists.sr.ht"] with a useful subject line and a description.

Please make sure to include the following information:

@itemlist[
@item{Which URL can I visit to see it for myself?}
@item{Which part of the page are you talking about?}
@item{Does it happen every time?}
]

Thanks!

@; -----------------------------------------------------------------------------

@section{Running}

@subsection{Running a compiled executable}

This method is recommended for people who do not want to edit the source code.

The distribution includes the Racket runtime, libraries, and everything else needed to run BreezeWiki.

@itemlist[#:style 'ordered
@item{Download the distribution: @url{https://cadence.moe/friends/breezewiki-dist.tar.gz}}
@item{Unpack the archive.}
@item{Execute the binary @code{breezewiki-dist/bin/dist}.}
]

@subsection{Running the source code}

This method is recommended for people who want to edit the source code, or for people who can't use the compiled distribution.

@itemlist[#:style 'ordered
@item{Install Racket. Please install the latest version. 8.4 or later is required.}
@item{Clone the repository from @url{https://gitdab.com/cadence/breezewiki}.}
@item{Run @code{raco pkg install --auto --skip-installed} in the repository to install dependencies.}
]

Now you can start BreezeWiki using one of the following methods.

@itemlist[
@item{Run @code{racket dist.rkt} to start BreezeWiki.}
@item{Evaluate @code{breezewiki.rkt} in DrRacket or in the Racket REPL to start BreezeWiki with module hot-reloading. Helpful for development!}
]

To be able to start up BreezeWiki faster, use @code{raco make dist.rkt} to byte-compile individual files.

@; -----------------------------------------------------------------------------

@section{Configuration}

@subsection{File}

Configuration options are added to the @code{config.ini} file. It is a regular INI file.

If you do not specify a specific option, the internal default will be used. If the file is missing or empty, all defaults will be used.

If you're using a compiled distribution of BreezeWiki, the main @code{config.ini} file will actually be a symlink to the real location of the file. Make sure not to erase the symlink, or your settings will be ignored!

@subsection{Example}

Here is an example configuration file. It shows all the available settings and all their defaults.
@verbatim{
canonical_origin =
debug = false
port = 10416
}

@subsection{Format}

@itemlist[
@item{A line with an equals sign @code{=} defines one setting.}
@item{The text before the equals sign is the @italic{key}.}
@item{The text after the equals sign is the @italic{value}. It may be empty.}
@item{Quote marks are optional - they are never necessary.}
@item{Spacing around the equals sign is optional.}
@item{@italic{False} values are represented by either empty space, or the text @code{false}. Anything else is @italic{True}.}
]

@subsection{Detailed Options}

@defthing[debug boolean #:value false]{
Enables debugging mode, for debugging BreezeWiki during development.

Enables more runtime checks and more verbose output. Turns off some browser caching.
}

@defthing[port value #:value "10416"]{
Which port to run the server on.
}

@defthing[canonical_origin value #:value ""]{
The URL that the homepage of the instance is intended to be accessed at.

For example, @code{https://breezewiki.com}
}