Справочные материалы и статьи по QSP

Внимание!!! Я опять занялся обновлением проекта. Многое может не работать.

Этот проект начинался как "Справочник по самым часто задаваемым вопросам из темы «Как сделать?» на форуме QSP.org", однако теперь он разросся вширь и помимо непосредственно справочника теперь здесь есть ещё два раздела.

• ИнформАрхив QSP — это раздел, в котором я собираю и компилирую старые статьи по QSP, которые мне нужны в одном месте для удобства.
• Статьи о QSP — это раздел, в котором я размещаю статьи о QSP, написанные непосредственно мной.
• Онлайн версия справочника по самым часто задаваемым вопросам из темы "Как сделать?" на форуме QSP.org.

Необходимо было генерировать справочник из исходников в виде готовых HTML-страниц и в виде fb2-файла. Поэтому были написаны два конвертера из моего формата текстовых файлов, похожего на markdown в HTML, и в FB2.

TODO

• Все статьи будут переведены на маркдаун, т.к. этот формат автоматически конвертируется гитхабом и обсидианом в HTML.
• Конвертер, который до сих пор обрабатывал мой собственный формат файлов, будет обрабатывать маркдаун. К сожалению, конвертеры markdown-to-html полное говно и не удовлетворяют моим нуждам.
• Структура статей теперь будет полностью прописываться в специальных json-файлах, вплоть до пути к исходнику и к конечному файлу на деплой.

Пути в html.json должны записываться относительно папки, в которой расположен билдер HTML-файлов.

Конвертер

Конвертирует исходники в набор готовых страниц HTML, между которыми создаются перекрёстные ссылки, в т.ч. ссылки для перелистывания страниц по порядку.

При конвертировании опирается на специальный опорный файл html.json, в котором прописывается некоторая структура:

{
	// все пути прописываются относительно билдера
	"book-name": "manual", // условное название сборки. В данном случае собираю справочник

	// Исходники -> конечные файлы
	"source-target": {
		// словарь состоит из пар: путь исходника - путь конечного файла
	},
	"source-folder": "..\\..\\[source]\\ИнформАрхив QSP",
	// папка, в которой будут размещаться страницы и fb2-документ после билдинга
	"output-folder": "..\\..\\informarch",

	// сборочник для html-версии справочника
	"project-html":
	{
		// начало перекрёстных ссылок внутри справочника
		"cross-link": "https://aleksversus.github.io/howdo_faq/informarch/",
		// верх html-страницы
		"head": "..\\..\\[source]\\ИнформАрхив QSP\\add\\02_start.html",
		// низ html-страницы
		"foot": "..\\..\\[source]\\ИнформАрхив QSP\\add\\03_end.html",
		// файл с содержанием справочника
		"head-contents": "..\\..\\[source]\\ИнформАрхив QSP\\000_soderzhanie_0000.txt-light"
	},
	
	// сборочник для fb2-версии справочника
	"project-fb2":
	{
		// название выходного файла
		"output-file":"informarch.%TIME%.fb2",
		// начальные строки файла
		"book-info": "..\\..\\[source]\\ИнформАрхив QSP\\add\\fb2_head.xml",
		// конечные строки файла со всеми бинарниками
		"binary": "..\\..\\[source]\\ИнформАрхив QSP\\add\\fb2_footer.xml"
	}
}

Файлы исходников должны именоваться только латиницей.

В конце каждого исходника ставится порядковый номер (в порядке создания, а не в порядке следования в папке).

В начале имени каждого исходника можно вставлять число и символ нижнего подчёркивания. Это помогает размещать исходники в нужном порядке, как страницы. Эти числа удаляются из имени при генерации HTML-файла, таким образом, даже если мы меняем расположение исходников в папках и разделах, имена конечных HTML-файлов останутся неизменны и уникальны, и таким образом ссылки на эти файлы не будут затираться.

Необходимо фиксировать номера последних файлов по каждому разделу. Для этого в папке res предусмотрена папка [count]. В ней лежат файлы с последним числом для каждого нового файла раздела.

Альт-архив для wiki.qsp.org. Редакция 2022.12.29: Справка по QSP.