public inbox for ~johnnyrichard/olang-devel@lists.sr.ht
 help / color / mirror / code / Atom feed
* [PATCH olang v1] docs: Create olang manual document bootstrap
@ 2024-09-05 19:38 Johnny Richard
  2024-09-05 22:52 ` Carlos Maniero
  0 siblings, 1 reply; 3+ messages in thread
From: Johnny Richard @ 2024-09-05 19:38 UTC (permalink / raw)
  To: ~johnnyrichard/olang-devel; +Cc: Johnny Richard

The idea behind the manual document is to provide a good reference for
anyone who wants to start write projects on olang and contribute to the
language.

We considered to use texinfo since it makes very convenient to
export the documentation as PDF and .info (terminal friendly) files.

This manual document also incorporates the contribution guide previously
documented on olang web site.

Signed-off-by: Johnny Richard <johnny@johnnyrichard.com>
---
 docs/Makefile                       |  12 +-
 docs/manual/.gitignore              |   6 +
 docs/manual/Makefile                |  10 ++
 docs/manual/contribution-guide.texi | 253 ++++++++++++++++++++++++++++
 docs/manual/getting-started.texi    |   2 +
 docs/manual/installation.texi       |   2 +
 docs/manual/introduction.texi       |   3 +
 docs/manual/olang.texi              |  41 +++++
 docs/manual/style.css               | 113 +++++++++++++
 docs/pages/contribute.md            | 154 -----------------
 docs/pages/getting-started.md       |   3 -
 docs/template.html                  |   5 +-
 12 files changed, 443 insertions(+), 161 deletions(-)
 create mode 100644 docs/manual/.gitignore
 create mode 100644 docs/manual/Makefile
 create mode 100644 docs/manual/contribution-guide.texi
 create mode 100644 docs/manual/getting-started.texi
 create mode 100644 docs/manual/installation.texi
 create mode 100644 docs/manual/introduction.texi
 create mode 100644 docs/manual/olang.texi
 create mode 100644 docs/manual/style.css
 delete mode 100644 docs/pages/contribute.md
 delete mode 100644 docs/pages/getting-started.md

diff --git a/docs/Makefile b/docs/Makefile
index c890eca..b57617a 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -10,12 +10,13 @@ PAGES      := $(wildcard $(PAGES_DIR)/*.md)
 HTML_PAGES := $(patsubst $(PAGES_DIR)/%.md, $(SITE_DIR)/$(PAGES_DIR)/%.html, $(PAGES))
 
 .PHONY: all
-all:  $(BUILD_DIR) $(TARGET) $(PAGES) manpages
+all:  $(BUILD_DIR) $(TARGET) $(PAGES) manpages manual
 
 .PHONY: clean
 clean:
 	rm -rf $(BUILD_DIR)
 	rm -f $(DIST_FILE)
+	make -C manual clean
 
 .PHONY: dist
 dist: $(DIST_FILE)
@@ -23,6 +24,10 @@ dist: $(DIST_FILE)
 .PHONY: manpages
 manpages: $(BUILD_DIR) $(MANPAGES)/olang.1
 
+.PHONY: manual
+manual: $(SITE_DIR)/manual/index.html
+
+
 $(MANPAGES)/%.1: manpages/%.md
 	$(PANDOC) -s -t man $< > $@
 
@@ -37,5 +42,10 @@ $(BUILD_DIR):
 	@mkdir -p $(SITE_DIR)/$(PAGES_DIR)
 	@mkdir -p $(MANPAGES)
 
+$(SITE_DIR)/manual/index.html: manual/*.texi
+	make -C manual
+	rm -rf $(SITE_DIR)/manual
+	mv manual/html $(SITE_DIR)/manual
+
 $(SITE_DIR)/$(PAGES_DIR)/%.html: $(PAGES_DIR)/%.md
 	$(PANDOC) -s --template template.html -f markdown -t html --toc $< > $@
diff --git a/docs/manual/.gitignore b/docs/manual/.gitignore
new file mode 100644
index 0000000..42927c0
--- /dev/null
+++ b/docs/manual/.gitignore
@@ -0,0 +1,6 @@
+html/
+olang.aux
+olang.info
+olang.log
+olang.pdf
+olang.toc
diff --git a/docs/manual/Makefile b/docs/manual/Makefile
new file mode 100644
index 0000000..070beba
--- /dev/null
+++ b/docs/manual/Makefile
@@ -0,0 +1,10 @@
+MAKEINFO=makeinfo
+
+all: html
+
+html: olang.texi introduction.texi installation.texi getting-started.texi contribution-guide.texi
+	$(MAKEINFO) --css-include=style.css -o html --html olang.texi
+
+.PHONY: clean
+clean:
+	rm -rf html
diff --git a/docs/manual/contribution-guide.texi b/docs/manual/contribution-guide.texi
new file mode 100644
index 0000000..4c6e458
--- /dev/null
+++ b/docs/manual/contribution-guide.texi
@@ -0,0 +1,253 @@
+@node Contribution Guide
+@chapter Contribution Guide
+
+O Programming Language is an independent project developed by volunteers around
+the world. Everyone is welcome to join us. If you want to catch up the language
+development, you can subscribe to our mailing list or join the #olang IRC
+channel on Libera network.
+
+Olang is hosted on a @strong{git repository}
+@url{https://git.sr.ht/~johnnyrichard/olang}
+
+@c ----------------------------------------------------------------------------
+
+@node Building the compiler
+@section Building the compiler
+
+The olang compiler is crafted in C. To build the project, you'll require
+merely three dependencies: @code{make}, @code{gcc} (version 11 or higher), and
+@code{clang-format} (version 14 or higher).
+
+@example
+$ make
+@end example
+
+If everything went well with the compilation, you should find a @code{olang}
+binary on the project root folder.
+
+As an optional step, you can install @code{texinfo}, @code{pandoc} and
+@code{texlive} to refresh this manual and the website. For more information
+read @ref{Writing Documentation}.
+
+@subsection Testing
+
+There are two layers of tests @strong{integration} and @strong{unit}. The
+integration test is going to execute the @code{olang} compiler and check if the
+generated binary acts as expected. Unit tests will test C functions.
+
+To run all tests you can execute:
+
+@example
+$ make check
+@end example
+
+@c ----------------------------------------------------------------------------
+
+@node Code Style
+@section Code Style
+
+Instead of delineating every element of our coding style, we have adopted the
+use of @strong{clang-format} to enforce the olang code style. Please refer to
+the format section below for guidance on its application.
+
+@subsection Code Formatting
+
+Checking for format issues:
+
+@example
+$ make format
+@end example
+
+Most of the common code style mistakes are fixed by:
+
+@example
+$ make format-fix
+@end example
+
+@subsection .editorconfig
+
+We also provide a @strong{.editorconfig} file at project's root. Follow
+@url{https://editorconfig.org/} to learn how to make it work with your favorite
+editor.
+
+@c ----------------------------------------------------------------------------
+
+@node Submitting Patches
+@section Submitting Patches
+
+Patches should be sent via email to @email{~johnnyrichard/olang-devel@@lists.sr.ht}
+mailing list.
+
+Olang uses @strong{git}.  We strongly recommend you to use @strong{git} if you
+want to make your contributor's life easier. The patches should be created with
+@code{git format-patch} and sent via @code{git send-email}.
+
+@subsection Formatting Patches
+
+All contributors are required to "sign-off" their commits (using @code{git
+commit -s}) to indicate that they have agreed to the
+@url{https://developercertificate.org/, Developer Certificate of Origin}.
+
+Before submit the patch, ensure the code follows our coding style and is
+well-tested. (every single patch must pass the test suite)
+
+Unlike many projects, olang has a
+@url{http://www.bitsnbites.eu/git-history-work-log-vs-recipe/, linear, 'recipe'
+style history}.  The patches should be small, digestible, stand-alone and
+functional.  Rather than a purely chronological commit history.
+
+Bellow there is an example of commit subject:
+
+@example
+Subject: [PATCH olang] parser: add bitwise shift binary operator expression
+                ^      ^       ^
+                |      |       |
+                |      |       - patch description
+                |      |
+                |      - module prefix
+                |
+                - project name
+@end example
+
+In the patch body we expect:
+
+@enumerate
+
+@item
+A good explanation on @strong{why} this change has been made
+
+@item
+All lines wrapped at 75 columns, which will be copied to the permanent
+changelog.
+
+@item
+An empty line
+
+@item
+The Signed-off-by: lines
+
+@item
+A marker line containing simply @code{---}
+
+@item
+Any additional comments not suitable for the changelog
+
+@item
+The actual patch (@code{diff} output).
+@end enumerate
+
+
+Sometimes you might need to break down your patch into multiple patches.  In
+this case a patchset should be sent.
+
+Patchesets MUST contain a @strong{cover letter} followed by a good description.
+It is easily achievable with the @code{--cover-letter} argument available on
+@code{git format-patch} and @code{git send-email} commands.
+
+
+@subsection Creating Patches
+
+You can create a patch using the command:
+
+@example
+$ git format-patch --cover-letter --base origin/main -M origin/main -o outgoing/
+@end example
+
+As described on @strong{Formatting Patches} the option @code{--cover-letter} is
+required for patchset.  Check the patches generated on @code{outgoing}
+folder and adjust the cover letter by replacing the "gaps" @strong{SUBJECT HERE}
+and @strong{BLURB HERE}.
+
+We recommend you to add the @code{--base} followed by a commit hash to help
+maintainers to know from where you changes are based on. (Optional but a good
+practice)
+
+@subsection Sending Patches
+
+Before sent patch, we suggest you to set the following properties on your
+@code{.git/config} file (This example assumes you are working on "olang" repository):
+
+@example
+[sendemail]
+    to = ~johnnyrichard/olang-devel@@lists.sr.ht
+[format]
+    subjectPrefix = PATCH olang
+@end example
+
+Make sure you email settings is correctly configured by running the
+@url{https://git-send-email.io} tutorial.  Once you have everything set, you
+can send the patches running the @code{git send-email} command as described
+bellow:
+
+@example
+$ git send-email outgoing/* --to=~johnnyrichard/olang-devel@@lists.sr.ht
+@end example
+
+@subsection The Review Process
+
+IMPORTANT: All emails MUST be written on @code{plain/text} format.
+
+Upon submission, you'll receive an automated email from our pipeline. If
+the check is successful, the olang maintainers will review your patch.
+Subsequently, you'll receive an email indicating whether your patch has
+been approved, requires changes, or has been rejected.
+
+We use a patch management system to track patch status at
+@url{https://lists.sr.ht/~johnnyrichard/olang-devel/patches}.
+
+Patch status meaning:
+
+@table @samp
+
+@item PROPOSED
+A new patch which needs review.
+
+@item NEEDS_REVISION
+The patch has been reviewed and changes was requested.
+
+@item SUPERSEDED
+The patch has been superseded by a new revision.
+
+@item APPROVED
+The patch has been approve and is waiting to be integrated.
+
+@item REJECTED
+The patch has been rejected and the work MUST be abandoned.
+
+@item APPLIED
+The patch has been integrated into the upstream.
+
+@end table
+
+If your patchset requires any modifications, you'll have to submit a new
+version of your patch (git is your friend here, use @code{rebase} to rewrite
+the history according to review comments).  The submission process remains
+unchanged, except for the addition of the version argument to the @code{git
+format-patch} command.
+
+@example
+$ git format-patch --cover-letter -M origin/main -o outgoing/ -v2
+@end example
+
+Whenever you need to reply emails comments, please avoid
+@url{https://en.wikipedia.org/wiki/Posting_style, top posting}, do
+@strong{botton posting} instead.  Read more about it here
+@url{https://useplaintext.email/#etiquette}.
+
+@c ----------------------------------------------------------------------------
+
+@node Writing Documentation
+@section Writing Documentation
+
+@c ----------------------------------------------------------------------------
+
+@node Development Mailing List
+@section Development Mailing List
+
+Send a @strong{plain text} email to
+@email{~johnnyrichard/olang-devel+subscribe@@lists.sr.ht} to subscribe to our
+deve mailing list.
+
+You should be able to find older threads by searching into our archives, which
+is hosted at @url{https://lists.sr.ht/~johnnyrichard/olang-devel}.
+
diff --git a/docs/manual/getting-started.texi b/docs/manual/getting-started.texi
new file mode 100644
index 0000000..e94f124
--- /dev/null
+++ b/docs/manual/getting-started.texi
@@ -0,0 +1,2 @@
+@node Getting Started
+@chapter Getting Started
diff --git a/docs/manual/installation.texi b/docs/manual/installation.texi
new file mode 100644
index 0000000..ef79184
--- /dev/null
+++ b/docs/manual/installation.texi
@@ -0,0 +1,2 @@
+@node Installation
+@chapter Installation
diff --git a/docs/manual/introduction.texi b/docs/manual/introduction.texi
new file mode 100644
index 0000000..4fb7cbc
--- /dev/null
+++ b/docs/manual/introduction.texi
@@ -0,0 +1,3 @@
+@node Introduction
+@chapter Introduction
+
diff --git a/docs/manual/olang.texi b/docs/manual/olang.texi
new file mode 100644
index 0000000..3ad28f4
--- /dev/null
+++ b/docs/manual/olang.texi
@@ -0,0 +1,41 @@
+\input texinfo
+
+@settitle Olang Reference Manual 0.0.1
+
+@copying
+This manual documents Olang.
+
+Copyright @copyright{} 2024 olang mantainers.
+@end copying
+
+@titlepage
+@title Olang Reference Manual
+@page
+@vskip 0pt plus 1fill
+@insertcopying
+@end titlepage
+
+@contents
+
+@node Top
+@top Olang Reference Manual
+
+This document describes O programming language (Olang). A simple system
+programming language.
+
+@menu
+* Introduction::
+* Installation::
+* Getting Started::
+* Contribution Guide::
+@end menu
+
+@include introduction.texi
+
+@include installation.texi
+
+@include getting-started.texi
+
+@include contribution-guide.texi
+
+@bye
diff --git a/docs/manual/style.css b/docs/manual/style.css
new file mode 100644
index 0000000..41b1b3f
--- /dev/null
+++ b/docs/manual/style.css
@@ -0,0 +1,113 @@
+@font-face {
+  font-family: 'Red Hat Mono';
+  font-style: italic;
+  font-weight: 300;
+  font-display: swap;
+  src: url(https://johnnyrichard.com/static/fonts/RedHatMono-Italic.ttf) format('truetype');
+}
+@font-face {
+  font-family: 'Red Hat Mono';
+  font-style: italic;
+  font-weight: 500;
+  font-display: swap;
+  src: url(https://johnnyrichard.com/static/fonts/RedHatMono-BoldItalic.ttf) format('truetype');
+}
+@font-face {
+  font-family: 'Red Hat Mono';
+  font-style: normal;
+  font-weight: 300;
+  font-display: swap;
+  src: url(https://johnnyrichard.com/static/fonts/RedHatMono-Regular.ttf) format('truetype');
+}
+@font-face {
+  font-family: 'Red Hat Mono';
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(https://johnnyrichard.com/static/fonts/RedHatMono-SemiBold.ttf) format('truetype');
+}
+
+:root {
+  --background-color: #f4f4f4;
+  --text-color: black;
+  --link-color: #4e5289;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background-color: #26282B;
+    --text-color: white;
+    --link-color: #8c91db;
+  }
+}
+
+h1, h2, h3, h4, h5, h6, b, strong {
+  font-weight: 500;
+}
+
+div.example {
+  margin: 0;
+}
+
+body {
+  background: var(--background-color);
+  color: var(--text-color);
+  margin: 0;
+  padding: 0 40px;
+}
+
+body, pre {
+  font-weight: 300;
+  font-family: "Red Hat Mono";
+  font-size: 1.4rem;
+}
+
+a {
+  color: var(--link-color);
+}
+
+body > * {
+  max-width: 1024px;
+  margin: 10px auto;
+}
+
+header > h1 {
+  font-weight: normal;
+}
+
+nav, header > h1 {
+  text-align: center;
+}
+
+header {
+  margin-top: 70px;
+  margin-bottom: 20px;
+}
+
+footer {
+  margin: 20px auto;
+}
+
+body > * {
+  line-height: 1.75rem;
+  overflow: hidden;
+}
+
+pre {
+  background: rgba(0,0,0, 0.75);
+  color: white;
+  padding: 1.5rem;
+  max-width: 100%;
+  overflow: auto;
+  font-size: large;
+  line-height: 1;
+}
+
+.logo-name {
+  font-size: 3.2rem;
+  font-weight: bold;
+}
+
+ol {
+  margin-left: 1.5rem;
+}
diff --git a/docs/pages/contribute.md b/docs/pages/contribute.md
deleted file mode 100644
index a6dfd04..0000000
--- a/docs/pages/contribute.md
+++ /dev/null
@@ -1,154 +0,0 @@
-% Contribute
-
-We're thrilled to have you here! Your interest in making olang the most
-exceptional and straightforward language ever is greatly appreciated.
-
-In this document, we'll outline how you can begin contributing to olang.  First
-and foremost, clone the project if you haven't done so already.
-
-``` {.sh}
-git clone https://git.sr.ht/~johnnyrichard/olang
-```
-
-Dependencies
-------------
-
-The olang compiler is crafted in C. To build the project, you'll require
-merely three dependencies: **make**, **gcc** (version 11 or higher), and
-**clang-format** (version 14 or higher).
-
-As an optional step, you can install **sphinx** to refresh this
-documentation.
-
-Code style
-----------
-
-Instead of delineating every element of our coding style, we have
-adopted the use of **clang-format** to enforce the olang code style.
-Please refer to the **Format** section below for guidance on its
-application.
-
-### Format
-
-Checking for format issues:
-
-``` {.sh}
-make format
-```
-
-Most of the common code style mistakes are fixed by:
-
-``` {.sh}
-make format-fix
-```
-
-### .editorconfig
-
-We also provide a **.editorconfig** file at project\'s root. Follow
-<https://editorconfig.org/> to learn how to make it work with your
-favorite editor.
-
-Testing
--------
-
-There are two layers of tests **integration** and **unit**. The
-integration test is going to execute the **olang** compiler and check if
-the generated binary acts as expected. Unit tests will test C functions.
-
-For both unit and integration we use **munit** framework:
-<https://nemequ.github.io/munit/>.
-
-To execute tests you can execute:
-
-``` {.sh}
-make check
-```
-
-Submitting a patch
-------------------
-
-All contributors are required to "sign-off" their commits (using git commit -s)
-to indicate that they have agreed to the [Developer Certificate of
-Origin](https://developercertificate.org/).
-
-Before submit the patch, ensure the code follows our coding style and is
-well-tested. After that, you\'re good to follow the steps bellow.
-
-### Step 1: Commit your changes
-
-Begin by committing your modifications with a detailed and significant
-commit message. We take great pleasure in maintaining a record of our
-changes over time. Skeptical? Execute a **git log** command and admire
-the well-documented history we've created so far.
-
-But it isn\'t all about personal preference. We use a email-driven
-workflow to propose our changes, meaning the commit message you write is
-the email the olang maintainers will get. I won't go into the perks of
-the email-driven workflow here, but you can check it out at
-<https://drewdevault.com/2018/07/02/Email-driven-git.html>.
-
-#### Best practices
-
-1. Write single-purpose commits.
-2. Write a meaningful commit message.
-3. Every commit must be production ready.
-    - If the tests or the format check fail, you should not create a fix
-      commit. Instead, you should amend the commit that caused the issue and
-      then resend the patchset.
-
-### Step 2: Create your patch
-
-You can create a patch using the command:
-
-``` {.sh}
-git format-patch --cover-letter -M origin/main -o outgoing/
-```
-
-### Step 3: Write a cover letter:
-
-The command above generates a **outgoing/0000-cover-letter.patch** file.
-
-The cover letter is like a pull request description on Github. Replace
-the \*\*\* SUBJECT HERE \*\*\* with the patchset title and the
-\*\*\* BLURB HERE \*\*\* with a synopsis of your changes.
-
-If you are sending a single-commit patch you can remove the
-**\--cover-letter** argument from **git format-patch** and skip this
-step.
-
-### Step 4: Submit your patch
-
-Make sure you have configured your **git send-email**. You can learn how
-to configure it here:
-<https://git-scm.com/docs/git-send-email#_examples>
-
-Once you have everything set you just need to send the patch over our
-mailing list.
-
-``` {.sh}
-git send-email outgoing/* --to=~johnnyrichard/olang-devel@lists.sr.ht
-```
-
-### The review process
-
-Upon submission, you'll receive an automated email from our pipeline. If
-the check is successful, the olang maintainers will review your patch.
-Subsequently, you'll receive an email indicating whether your patch has
-been approved, requires changes, or has been rejected.
-
-### Submitting changes in a patchset
-
-If your patchset requires any modifications, you'll have to submit a new
-version of your patch. The submission process remains unchanged, except
-for the addition of the version argument to the **git format-patch**
-command.
-
-``` {.sh}
-git format-patch --cover-letter -M origin/main -o outgoing/ -v2
-```
-
-After send a new email with **git send-email**.
-
-------------------------------------------------------------------------
-
-Thanks again and happy hacking!
diff --git a/docs/pages/getting-started.md b/docs/pages/getting-started.md
deleted file mode 100644
index eb4822a..0000000
--- a/docs/pages/getting-started.md
+++ /dev/null
@@ -1,3 +0,0 @@
-% Getting stated
-
-WIP
diff --git a/docs/template.html b/docs/template.html
index 774ab49..0f5a207 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -13,7 +13,7 @@
     }
     @media (prefers-color-scheme: dark) {
       :root {
-        --background-color: #2b2b2b;
+        --background-color: #26282B;
         --text-color: white;
         --link-color: #8c91db;
       }
@@ -70,9 +70,8 @@
     <h1><span class="logo-name">olang</span> | O Programming Language</h1>
     <nav>
       [ <a href="/">Home</a> ]
-      [ <a href="/pages/getting-started.html">Getting started</a> ]
+      [ <a href="/manual">Manual</a> ]
       [ <a href="/pages/language-specification.html">Specification</a> ]
-      [ <a href="/pages/contribute.html">Contribute</a> ]
       [ <a href="https://sr.ht/~johnnyrichard/olang/sources" target="_blank">Sources ↗</a> ]
       [ <a href="https://sr.ht/~johnnyrichard/olang/lists" target="_blank">Mailing list ↗</a> ]
     </nav>

base-commit: 7b032597a6009614c8032e88f16803555f41df71
-- 
2.46.0


^ permalink raw reply	[flat|nested] 3+ messages in thread
end of thread, other threads:[~2024-09-06 14:49 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-09-05 19:38 [PATCH olang v1] docs: Create olang manual document bootstrap Johnny Richard
2024-09-05 22:52 ` Carlos Maniero
2024-09-06 14:49   ` Johnny Richard

Code repositories for project(s) associated with this public inbox

	https://git.johnnyrichard.com/olang.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox