Build .adoc Files for GitHub Pages from f5a51e6

.gitignore

@@ -0,0 +1,14 @@
+*.o
+*.so
+*.dll
+*.dylib
+*.d
+*.gcov
+*~
+src/structs-example.c
+src/tmp-*.g
+.vscode
+\#*\#
+coverage
+*.info
+.tup

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "clang-format-hooks"]
+	path = clang-format-hooks
+	url = https://github.com/barisione/clang-format-hooks.git

00-guidebook.header

@@ -0,0 +1,20 @@
+:source-highlighter: highlightjs
+:icons: font
+:numbered:
+:toc: left
+:pp: ++
+:title-page:
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
+= C-xrefactory - a C/Yacc refactoring and code browsing tool - Design Documentation
+v{VERSION} - Generated {localdate}
+
+WARNING: This document is very much a work in progress.
+
+

LICENSE

@@ -0,0 +1,27 @@
+**********************************************************************
+*                  C-xrefactory License Agreement                      *
+**********************************************************************
+
+1.)  SOFTWARE:  C-xrefactory and associated  documentation is referred
+as "the Software" in the rest of this document.
+
+2.) GPL:  You can use and  distribute the software under  the terms of
+the  GNU General Public  License version  2 as  published by  the Free
+Software  Foundation.  You  should have  received  a copy  of the  GNU
+General Public License  along with this program; if  not, write to the
+Free Software Foundation,  Inc., 59 Temple Place -  Suite 330, Boston,
+MA 02111-1307, USA.
+
+3.) USAGE:  You are  free to download,  install, modify and  store the
+software without a  charge. You are free to  use this software without
+charges in any project whether commercial or not.
+
+4.) WARRANTY: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER  EXPRESS OR IMPLIED,  INCLUDING, BUT NOT LIMITED  TO, THE
+IMPLIED  WARRANTIES  OF  MERCHANTABILITY,  FITNESS  FOR  A  PARTICULAR
+PURPOSE, OR NON-INFRINGEMENT.
+
+**********************************************************************
+
+
+

Makefile

@@ -0,0 +1,20 @@
+all: guidebook.adoc
+	@echo "'make start' to start Structurizr, 'make html' to make html docs"
+
+start:
+	docker pull structurizr/lite
+	docker run -it --rm -p 8080:8080 -v $(PWD):/usr/local/structurizr structurizr/lite
+
+html: manual.html guidebook.html
+
+manual.html: manual.adoc
+	asciidoctor manual.adoc
+
+guidebook.html: guidebook.adoc
+	asciidoctor -r asciidoctor-diagram guidebook.adoc
+
+# The guidebook is the one and only document in docs b.c. Structurizr likes it that way
+# But to publicise it using GitHub action we need to concat them all into one document
+guidebook.adoc: docs/*.adoc docs/*.md 00-guidebook.header
+	ls 00-guidebook.header docs/*.adoc docs/*.md | sort | xargs -I {} sh -c 'cat {}; echo ""' > guidebook.adoc
+	sed -i '' 's|image::embed:\(.*\)\[\]|image::\.structurizr/images/\1-thumbnail.png[]|g' guidebook.adoc

README.md

@@ -0,0 +1,58 @@
+# Documentation
+
+We continually try to document architecture and design using
+Structurizr (cd to this directory and run `../utils/structurizr`, then
+open http://localhost:8080).
+
+The documentation consists of three elements
+
+- documentation
+- diagrams/model
+- decisions
+
+## Documentation
+
+In the subdirectory `docs` each section in the documentation
+is stored in a separate Markdown or AsciiDoc file. In it diagrams
+generated from the system/architecture model is included.
+
+At this point the user manual is still a separate AsciiDoc file.
+
+## Diagrams/Model
+
+All diagrams are generated by Structurizr from the model in `workspace.dsl`.
+
+## Decisions
+
+We document significant, including architecture-relevant, decisions
+using classic ADRs stored as separate files in the `adr`
+subdirectory. There are some good documentation and ideas about ADRs
+[here|https://github.com/joelparkerhenderson/architecture_decision_record]
+and [here|https://adr.github.io/].
+
+We have not picked a template yet (and might never do) so write what
+seems relevant.
+
+The ADRs should be Markdown files given a name after the following
+pattern:
+
+    <nnn>--<name>.md
+
+- <nnn> - sequential number
+- <name> should be a a present tense imperative verb phrase,
+  e.g. "choose_database" or "manage_password" because this will match
+  what the reader want to know when coming here
+
+The ADR should at least contain something like a
+[Y-statement|https://www.infoq.com/articles/sustainable-architectural-design-decisions/]
+following this pattern:
+
+    In the context of <use case/user story u>,
+    facing <concern c>
+    we decided for <option o> and neglected <other options>,
+    to achieve <system qualities/desired consequences>,
+    accepting <downside/undesired consequences>,
+    because <reason for accepting downside>.
+
+NOTE: As the whole c-xrefactory project is a hobby project where I'm
+constantly trying out and learning things, this is also a WIP.

TROUBLES

@@ -0,0 +1,112 @@
+**********************************************************************
+*                               TROUBLES                             *
+**********************************************************************
+NOTE: These are old instructions and might not be appropriate any more.
+----------------------------------------------------------------------
+You see a message of form:
+
+:[warning] main.c:160, can't open file tin.h
+
+This  means that  the directory  containing  the 'tin.h'  file is  not
+specified  in  your include  paths.   You  should  edit your  personal
+'~/.c-xrefrc' file and add there the
+
+    -I directory
+
+option, where directory is the directory containing the 'tin.h' file.
+
+----------------------------------------------------------------------
+While creating cross references of a file 'myfile.c' you see a message
+like:
+
+'myfile.c':[warning] stdlib.h:32, can't open file stddef.h
+
+meaning that the file 'stddef.h', included from the standard header
+'stdlib.h', was not found. This can occur when your compiler is using
+non standard include directories. In this case you have to determine
+which directory contains 'stdlib.h' and add this directory, using the
+'-I' option, into your '~/.c-xrefrc' file.  In order to determine the
+include directory of your compiler, you can pre-process your input
+file with your compiler and look for the place where the searched file
+was included, i.e. (following our example) type:
+
+    gcc -E myfile.c | grep "stddef.h"
+
+and you will obtain an output in the form:
+
+ #line 1 "/usr/lib/gcc-lib/i386-redhat-linux/2.7.2.3/include/stddef.h" 1 3
+
+Here you see the directory containing the file in question and you can
+now add the line:
+
+    -I /usr/lib/gcc-lib/i386-redhat-linux/2.7.2.3/include
+
+to your '.c-xrefrc' file.
+
+----------------------------------------------------------------------
+While calling code completion you receive the error message:
+
+    '[error] sorry, memory mbMemory overflowed over borne'
+
+The macro-body memory overflowed. This probably means that you have
+invoked the completion inside a macro invocation with no closing
+parentheses. Just put a closing parenthesis after the macro argument
+and call the completion again.  If this does not work, read the
+following item.
+
+----------------------------------------------------------------------
+You receive an error message of the form :
+
+    '[error] sorry, memory XXX overflowed over borne'
+
+This means that some internal memory table overflowed.  This problem
+occurs when your files are bigger than expected.  In the
+'src/constants.h' file find the corresponding constant, which should
+be something like SIZE_XXX, adjust it to fit your application size,
+and re-compile C-xrefactory.
+
+
+----------------------------------------------------------------------
+You see a message like:
+
+    "[error] position over MAX_REFERENCABLE_LINE"
+or
+    "[error] position over MAX_REFERENCABLE_COLUMN"
+
+
+It means that your program is too long. There are either too many
+lines in a single file, or a line which is too long.
+
+C-xrefactory only supports files below ~4 million lines (and
+columns). If you encounter this you should really rewrite your
+application and report the case on
+https://github.com/thoni56/c-xrefactory.
+
+----------------------------------------------------------------------
+You see a message like:
+
+    "[warning] cx_memory resizing required"
+
+This happens when the memory which stores cross references overflows
+and cannot be resized anymore.  If this happens when calling an
+editing macro you should probably put the "-noincluderefs" option in
+your .c-xrefrc option file.  If this does not help edit the
+'src/constants.h' file and increase the CX_MEMORY_CHUNK_SIZE constant
+value and recompile.  If the message appears while creating cross
+references you will need to either use the "-mf<n>" command line
+option, or increase the CX_MEMORY_CHUNK_SIZE constant as in the
+previous case.
+
+
+----------------------------------------------------------------------
+
+
+**********************************************************************
+*                           ACKNOWLEDGMENTS                          *
+**********************************************************************
+
+Many thanks to Ed Soniat, Paul Ruben and Reuben Thomas for their help
+with Xrefactory documentation. Thanks to Dmitry Kuminov for OS/2 port.
+Thanks also to Jean-loup Gailly and Mark Adler for their generous
+license to use zlib library, allowing us to read compressed .jar
+archives.

Untabify

@@ -0,0 +1,2 @@
+#!/bin/sh
+find . \( -name "*.c" -o -name "*.java" \) -exec emacs -batch -l ~/.emacs {} -f untabify-buffer \;

adr/0001-store-reference-data-in-text-files-with-encoding.md

@@ -0,0 +1,38 @@
+# Store Reference Data in Text Files with compacting encoding
+
+Date: 1990-01-01
+
+Actually somewhen in c-xrefactory early history
+
+## Status
+
+Accepted
+
+## Deciders
+
+Probably Marián and others
+
+## Where to store reference data in an effective and compact format
+
+### Y-Statement
+
+_In the context of_ effectively and compactly percisting reference data stored on disk,
+_facing the fact_ that we need to access it quickly and that it should always reflect the current content of source files
+_we decided for_ custom optimized and encoded file storage
+_and neglected_ database or free text storage
+_to achieve_ some level of storage
+_accepting_ complexity of access code and performance hits,
+_because_ it seemed right at the time.
+
+### Decision Drivers
+
+* Previous format seems to have been a more clear text version and the concern was (maybe) space on disk
+* Compacting the clear text format by encoding data, avoiding duplicate information due to space considerations?
+
+### Considered Options
+
+* Unknown
+
+### Decision Outcome
+
+Current intricately encoded text format...

adr/0002-remove-enum-and-struct-fill-macro-generation.md

@@ -0,0 +1,36 @@
+# Remove enum and struct fill macro generation
+
+Date: 2020-04-13
+
+## Status
+
+Accepted
+
+## Problem Statement and Context
+
+`c-xrefactory` has an option to generate macros for filling structs
+and turning enums into strings. This option requires a pre-pass of the
+c-xrefactory sources themselves to generate those macros before
+compilation of said sources. This creates a Catch-22 situation in that
+it requires a bootstrap step.
+
+It also makes the build scripts much more complicated and difficult to
+maintain.
+
+## Decision
+
+Replace the macros that are actually used and remove the generation
+feature from `c-xrefactory`. There is actually no real alternative.
+
+## Consequences and Risks
+
+Hopefully the sources will be easier to maintain and build scripts
+easier to modify.
+
+There is a slight risk that some functionality might be broken during
+the fairly simple, but not trivial, replacement.
+
+## Considered Options
+
+- Remove the functionality
+- Keep the functionality

adr/0003-use-markdown-architectural-decision-records.md

@@ -0,0 +1,31 @@
+# Use Markdown Architectural Decision Records
+
+Date: 2021-06-13
+
+## Status
+
+Superseded by [Use classic ADR:s for Architecture Decisions](0007-use-classic-adr-s-for-architecture-decisions.md)
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 2.1.0 - The Markdown Architectural Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR"
+* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) - The Y-Statements
+* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+* Formless - No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 2.1.0", because
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.
+* Version 2.1.0 is the latest one available when starting to document ADRs.