system/serenity
system/serenity
1
0
Fork 0
mirror of https://github.com/SerenityOS/serenity synced 2024-10-06 16:09:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: Move all file format documentation into its own manpage

Browse source 
The documentation is largely unchanged except for adoption into the
standard manpage format.
This commit is contained in:
kleines Filmröllchen 2022-06-16 16:47:46 +02:00 committed by Linus Groh
parent da25ac0d48
commit 9660f5d0e6
7 changed files with 125 additions and 83 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
Base/usr/share/man/man5/af.md Normal file
View file

@ -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).

51
Base/usr/share/man/man5/clipboard.md Normal file
View file

@ -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<String, String>` 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<String, ByteBuffer>` 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
```

1
Base/usr/share/man/man5/drag-and-drop.md Symbolic link
View file

@ -0,0 +1 @@
clipboard.md

17
Base/usr/share/man/man5/font.md Normal file
View file

@ -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).

16
Base/usr/share/man/man5/ipc.md Normal file
View file

@ -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/).

22
Base/usr/share/man/man5/postcreate.md Normal file
View file

@ -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).

83
Documentation/FileFormats.md
View file

@ -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<String, String>` 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<String, ByteBuffer>` 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).