From 9660f5d0e63dcde551391c03399ed5b233c2fd92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?kleines=20Filmr=C3=B6llchen?= Date: Thu, 16 Jun 2022 16:47:46 +0200 Subject: [PATCH] Documentation: Move all file format documentation into its own manpage The documentation is largely unchanged except for adoption into the standard manpage format. --- Base/usr/share/man/man5/af.md | 18 +++++ Base/usr/share/man/man5/clipboard.md | 51 +++++++++++++++ Base/usr/share/man/man5/drag-and-drop.md | 1 + Base/usr/share/man/man5/font.md | 17 +++++ Base/usr/share/man/man5/ipc.md | 16 +++++ Base/usr/share/man/man5/postcreate.md | 22 +++++++ Documentation/FileFormats.md | 83 ------------------------ 7 files changed, 125 insertions(+), 83 deletions(-) create mode 100644 Base/usr/share/man/man5/af.md create mode 100644 Base/usr/share/man/man5/clipboard.md create mode 120000 Base/usr/share/man/man5/drag-and-drop.md create mode 100644 Base/usr/share/man/man5/font.md create mode 100644 Base/usr/share/man/man5/ipc.md create mode 100644 Base/usr/share/man/man5/postcreate.md diff --git a/Base/usr/share/man/man5/af.md b/Base/usr/share/man/man5/af.md new file mode 100644 index 00000000000..d0bf5756ade --- /dev/null +++ b/Base/usr/share/man/man5/af.md @@ -0,0 +1,18 @@ +## Name + +af - Application File format + +## Synopsis + +The Application Files define System Menu entries and launcher file types / protocols. + +## Description + +.af files are human-readable and are a subset of the INI-format, have no easily detectable filemagic. These files define System Menu entries and launcher file types / protocols. + +They are stored in [`/res/apps`](../../../../res/apps). + +## See Also + +- [`Userland/Services/Taskbar/main.cpp`](../../../../../Userland/Services/Taskbar/main.cpp) +- `Launcher::load_handlers` in [`Userland/Services/LaunchServer/Launcher.cpp`](../../../../../Userland/Services/LaunchServer/Launcher.cpp). diff --git a/Base/usr/share/man/man5/clipboard.md b/Base/usr/share/man/man5/clipboard.md new file mode 100644 index 00000000000..9df4f071373 --- /dev/null +++ b/Base/usr/share/man/man5/clipboard.md @@ -0,0 +1,51 @@ +## Name + +clipboard - Data formats specific to Clipboard and drag & drop + +## Clipboard + +The clipboard feature works through the Clipboard server, which generally acts as a global storage or three things: +- a `String` mime type, +- a (potentially large) block of data, shared as an anonymous file, +- a `HashMap` of arbitrary metadata, depending on the mime type. + +See also [`Userland/Libraries/LibGUI/Clipboard.h`](../../../../../Userland/Libraries/LibGUI/Clipboard.h). + +## Drag & drop + +In contrast to the clipboard, the drag & drop feature works through WindowServer, and a bouquet of data is transmitted: +- a `[UTF8] String` to be displayed while dragging, +- a `HashMap` map that contains arbitrary data for a variety of possible mime types, +- a `Gfx::ShareableBitmap` to be displayed while dragging + +Drag & drop is most prominently supported by File Manager, Spreadsheet, and Terminal. +Various applications accept drag & drop to open files. + +## glyph/x-fonteditor (Clipboard-only) + +Requires the metadata-fields `count` (count of glyphs copied) and `first_glyph` (lowest codepoint that is copied), encoded as decimal strings. + +The data contains codepoint (encoded as host-endian u32), width and height (as u8's) and glyph bitmap data. It is encoded in width times height many bytes, either 0 (clear) or 1 (set). + +Implemented in `FontEditor::MainWidget::copy_selected_glyphs` and `FontEditor::MainWidget::paste_glyphs`, in [`Userland/Applications/FontEditor/MainWidget.cpp`](../../../../../Userland/Applications/FontEditor/MainWidget.cpp). + +## image/x-serenityos (Clipboard-only) + +Requires the metadata-fields `width`, `height`, `scale`, `format` (see `Gfx::BitmapFormat`), and `pitch`, encoded as decimal strings. + +The data is encoded according to `Gfx::determine_storage_format(BitmapFormat)`, so either as +BGRx8888, BGRA8888, RGBA8888, or 8-bit palette index. Note that the palette is not transferred. + +Implemented in [`Clipboard::set_bitmap` and `Clipboard::DataAndType::as_bitmap()`](../../../../../Userland/Libraries/LibGUI/Clipboard.cpp). + +## text/uri-list (Clipboard and drag & drop) + +Newline-delimited set of URIs. Used by File Manager, FileSystemModel, and Terminal. + +Example: + +``` +file:///home/anon/Desktop/Browser +file:///home/anon/Desktop/Help +file:///home/anon/Desktop/Home +``` diff --git a/Base/usr/share/man/man5/drag-and-drop.md b/Base/usr/share/man/man5/drag-and-drop.md new file mode 120000 index 00000000000..c45156163fc --- /dev/null +++ b/Base/usr/share/man/man5/drag-and-drop.md @@ -0,0 +1 @@ +clipboard.md \ No newline at end of file diff --git a/Base/usr/share/man/man5/font.md b/Base/usr/share/man/man5/font.md new file mode 100644 index 00000000000..272336b111e --- /dev/null +++ b/Base/usr/share/man/man5/font.md @@ -0,0 +1,17 @@ +## Name + +font - Bitmap Font File format + +## Synopsis + +The .font file format stores bitmap fonts in SerenityOS's own binary format. + +## Description + +These files contain bitmap definitions of fonts, either varying-width or fixed-width. + +The first four bytes contain the filemagic: `!Fnt` (0x21466e74). + +## See also + +- Format header definition in `Gfx::FontFileHeader` in [`Userland/Libraries/LibGfx/Font/BitmapFont.cpp`](../../../../../Userland/Libraries/LibGfx/Font/BitmapFont.cpp). diff --git a/Base/usr/share/man/man5/ipc.md b/Base/usr/share/man/man5/ipc.md new file mode 100644 index 00000000000..9efd931020a --- /dev/null +++ b/Base/usr/share/man/man5/ipc.md @@ -0,0 +1,16 @@ +## Name + +ipc - Inter Process Communication endpoint definition format + +## Synopsis + +The IPC format of SerenityOS is a domain-specific language (DSL) used to define communication endpoints for IPC. + +## Description + +These files are human-readable, have no easily detectable filemagic, and define IPC interfaces. +The format is loosely inspired by C++ headers. + +## See Also + +- [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/). diff --git a/Base/usr/share/man/man5/postcreate.md b/Base/usr/share/man/man5/postcreate.md new file mode 100644 index 00000000000..d7be930ed80 --- /dev/null +++ b/Base/usr/share/man/man5/postcreate.md @@ -0,0 +1,22 @@ +## Name + +postcreate - HackStudio postcreate scripts + +## Synopsis + +.postcreate shell scripts are executed by HackStudio after creating a new project. + +## Description + +It is possible to define project templates that set up HackStudio projects. These templates can contain custom setup logic in the form of a `*.postcreate` script in the template directory. The script name must match the template's (directory) name. Postcreate scripts are regular shell scripts. They are executed from an undeterminate directory with the following arguments: + +- The path to the postcreate script +- The name of the new project +- The path of the new project, i.e. not the parent directory it was created in +- The project name in a form that is safe for C++ namespaces + +The script may error out with a non-zero exit code, but the project is still created. The user is informed of the error. + +## See Also + +- `ProjectTemplate::create_project` in [`Userland/DevTools/HackStudio/ProjectTemplate.cpp`](../../../../../Userland/DevTools/HackStudio/ProjectTemplate.cpp). diff --git a/Documentation/FileFormats.md b/Documentation/FileFormats.md index 763b24ec48e..be7c479cef1 100644 --- a/Documentation/FileFormats.md +++ b/Documentation/FileFormats.md @@ -2,83 +2,6 @@ This document summarizes all non-standard file formats, data formats, and mime-types used by Serenity. -## Clipboard - -The clipboard feature works through the Clipboard server, which generally acts as a global storage or three things: -- a `String` mime type, -- a (potentially large) block of data, shared as an anonymous file, -- a `HashMap` of arbitrary metadata, depending on the mime type. - -See also [`Userland/Libraries/LibGUI/Clipboard.h`](../Userland/Libraries/LibGUI/Clipboard.h). - -## Drag & drop - -In contrast to the clipboard, the drag & drop feature works through WindowServer, and a bouquet of data is transmitted: -- a `[UTF8] String` to be displayed while dragging, -- a `HashMap` map that contains arbitrary data for a variety of possible mime types, -- a `Gfx::ShareableBitmap` to be displayed while dragging - -Drag & drop is most prominently supported by File Manager, Spreadsheet, and Terminal. -Various applications accept drag & drop to open files. - -## glyph/x-fonteditor (Clipboard-only) - -Requires the metadata-fields `count` (count of glyphs copied) and `first_glyph` (lowest codepoint that is copied), encoded as decimal strings. - -The data contains codepoint (encoded as host-endian u32), width and height (as u8's) and glyph bitmap data. It is encoded in width times height many bytes, either 0 (clear) or 1 (set). - -Implemented in `FontEditor::copy_selected_glyphs` and `FontEditor::paste_glyphs`, in [`Userland/Applications/FontEditor/MainWidget.cpp`](../Userland/Applications/FontEditor/MainWidget.cpp). - -## image/x-serenityos (Clipboard-only) - -Requires the metadata-fields `width`, `height`, `scale`, `format` (see `Gfx::BitmapFormat`), and `pitch`, encoded as decimal strings. - -The data is encoded according to `Gfx::determine_storage_format(BitmapFormat)`, so either as -BGRx8888, BGRA8888, RGBA8888, or 8-bit palette index. Note that the palette is not transferred. - -Implemented in [`Clipboard::set_bitmap` and `Clipboard::DataAndType::as_bitmap()`](../Userland/Libraries/LibGUI/Clipboard.cpp). - -## text/uri-list (Clipboard and drag&drop) - -Newline-delimited set of URIs. Used by File Manager, FileSystemModel, and Terminal. - -Example: - -``` -file:///home/anon/Desktop/Browser -file:///home/anon/Desktop/Help -file:///home/anon/Desktop/Home -``` - -## Application File (`*.af` files) - -These files are human-readable and are a subset of the INI-format, have no easily detectable filemagic. -These files define System Menu entries and launcher file types / protocols. - -They are stored in [`/res/apps`](../Base/res/apps). - -See also [`Userland/Services/Taskbar/main.cpp`](../Userland/Services/Taskbar/main.cpp) and `Launcher::load_handlers` in [`Userland/Services/LaunchServer/Launcher.cpp`](../Userland/Services/LaunchServer/Launcher.cpp). - -## Font (`*.font` files) - -These files contain bitmap definitions of fonts, either varying-width or fixed-width. -The header definition can be found in `Gfx::FontFileHeader` in [`Userland/Libraries/LibGfx/Font/BitmapFont.cpp`](../Userland/Libraries/LibGfx/Font/BitmapFont.cpp). -Most prominently, the first four bytes contain the filemagic: `!Fnt`. - -## GUI Markup Language (`*.gml` files) - -These files are human-readable, have no easily detectable filemagic, and define GUI designs and layouts. -The format is strongly influenced by QML, the Qt Modeling Language. - -See the [GML manpage(s)](../Base/usr/share/man/man5/GML.md), [GML Playground(1)](../Userland/DevTools/GMLPlayground/), and the [GML support in LibGUI](../Userland/Libraries/LibGUI/GML/). - -## Inter Process Communication (`*.ipc` files) - -These files are human-readable, have no easily detectable filemagic, and define IPC interfaces. -The format is loosely inspired by C++ headers. - -See also [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/`](../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/). - ## Inter Process Communication (through Unix sockets) The various services each have their own formats, all very similar, and automatically implemented through LibIPC. The specifics depend on the corresponding source `.ipc` file. @@ -91,9 +14,3 @@ In general, communication works by packets, which might have been sent in respon - the 32-bit endpoint magic (note that responses use the endpoint of the requesting packet, so the Clipboard server might use the endpoint magic 4008793515 to signal that this packet is a response) - the 32-bit message ID within that endpoint (sequentially assigned, starting at 1) - the data of that message itself (e.g. see `Messages::ClipboardServer::SetClipboardData::{en,de}code` in `Build/*/Userland/Services/Clipboard/ClipboardServerEndpoint.h`). - -## Postcreate (`*.postcreate` files) - -Shell-script executed by HackStudio after creating a new project. - -See also `ProjectTemplate::create_project` in [`Userland/DevTools/HackStudio/ProjectTemplate.cpp`](../Userland/DevTools/HackStudio/ProjectTemplate.cpp).