From b1d829c8dd7c115779710314dbda2b034835ff1e Mon Sep 17 00:00:00 2001 From: "Luke T. Shumaker" Date: Sat, 13 Apr 2024 16:24:36 -0600 Subject: wip --- contribs.yml | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++ gen.go | 79 +++++++++++++++++++++++++++++++++------- plan.html.tmpl | 63 ++++++++++++++++++++++++++++++-- plan.yml | 113 --------------------------------------------------------- upstreams.yml | 29 +++++++++++++++ 5 files changed, 255 insertions(+), 129 deletions(-) create mode 100644 contribs.yml delete mode 100644 plan.yml create mode 100644 upstreams.yml diff --git a/contribs.yml b/contribs.yml new file mode 100644 index 0000000..20ec3aa --- /dev/null +++ b/contribs.yml @@ -0,0 +1,100 @@ +tags: + docs: + prettyName: Documentation + desc: | + I'm working to improve documentation for GNU/Linux, but more + than that I'm working to improve the forms of documentation that + more skilled technical writers might be afraid or incapable of + working on: `--help` text, generated documentation, and auditing + documentation against the source code to make sure that it is + accurate and complete. + ARM: + prettyName: ARM support + desc: | + Not that folks can't use GNU/Linux on ARM (obviously, the + Raspberry Pi has been a huge success), but there's still a lot + more friction to using GNU/Linux on ARM compared to x86. I'm + working on that. + GI: + prettyName: GObject Introspection + desc: | + GObject Introspection (which is a terrible name for what it is, + btw) is a cross-(language-runtime) object system. GObject was + an object system for C that game out of GTK+, and then GObject + Introspection was created as a way to specify the ABI for + working with an object, so that GObjects could be used from + other languages. I think that GObject Introspection is a really + cool technology that can be the basis of reducing friction + between languages, but it needs better/more-ubiquitous tooling. + +contributions: + - urls: [https://github.com/flori/json/pull/567] + tags: [Ruby, JSON, SoftwareFreedom] + desc: | + ruby-json contains code that is not Free under the FSF's + definition, not Open Source under the OSI's definition, and not + GPL-compatible. This has coused much consternation among folks + who care about any of those 3 things. + + This PR replaces that non-Free code with Free code, removing + friction for Ruby users on GNU/Linux distros that care about + those 3 things. + - urls: [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/merge_requests/328] + tags: [ARM] + sponsored-by: Umorpha Systems + desc: | + To do its work, mkinitcpio needs to know the version number of + the Linux kernel that it is generating an image for; the normal + way that it knows this is to sniff the version number from the + kernel file. However, it fails to sniff the version number from + ARM zImage kernels, which means that Arch Linux ARM and Parabola + for ARM need to resort to hacks to get mkinitcpio to work right. + + This PR removes that friction by teaching mkinitcpio to + understand ARM zImage files. + - urls: [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/merge_requests/277] + sponsored-by: Umorpha Systems + desc: | + One of the things going on in the secure-boot world is moving + toward "Unified Kernel Images" (UKI), which are when the kernel + and the init-ramdisk are bundled together into a single file to + reduce the risk of a compromised init-ramdisk being able to + compromise a secured kernel. This PR reduces friction when + using mkinitcpio to generate images directly as UKI without + generating a plain init-ramdisk first. + - urls: + - https://mailman.astron.com/pipermail/file/2024-April/001335.html + - https://github.com/file/file/commit/cf139abf35d07ebfd0c3edcab2fc400a211c0fbb + tags: [ARM] + desc: | + This PR improves its ability to detect information about Linux + kernel ARM zImage files. + - urls: + - https://mailman.astron.com/pipermail/file/2024-March/001327.html + - https://github.com/file/file/commit/3b92878ee277a6b6c0a37429e9edf5e5b55fcdd4 + tags: [docs] + desc: | + To do this, `file` reads a "magic" file that describes the magic + numbers that it might see in a file. This PR fixes a mistake in + the `magic(5)` manual for writing such files. + - urls: [https://github.com/diamondburned/gotk4/pull/140] + tags: [GI, docs] + desc: | + The not-quite-markdown format that `.gir` files use for + documentation is under-specified and hard to parse. Right now + I'm focusing on how to properly parse it, so that we can have + top-notch language-specific documentation for GI libraries. + + This PR is laying the groundwork for the new parser. + - urls: + - https://lists.ozlabs.org/pipermail/linux-erofs/2023-November/009765.html + - https://github.com/erofs/erofs-utils/commit/f528b82ffbcb15484a7195c1a1d08ece0ff67350 + - https://github.com/erofs/erofs-utils/commit/197e3294bcdf93f37d12989cd830a33c055b1a53 + - https://github.com/erofs/erofs-utils/commit/f97311883337eb7e0ded55e60995e6599eba73e5 + tags: [docs] + sponsored-by: Umorpha Systems + desc: | + This patchset improves the `--help` documentation and + man-pages the EroFS userspace tools, and reduces friction by + having `fsck.erofs` accept common command line flags that fsck + implementions for other filesystems take. diff --git a/gen.go b/gen.go index 39180ec..dbddd3b 100644 --- a/gen.go +++ b/gen.go @@ -4,7 +4,9 @@ import ( "bytes" _ "embed" "fmt" + "net/url" "os" + "path" "sigs.k8s.io/yaml" "strings" @@ -12,7 +14,7 @@ import ( "html/template" ) -type Plan struct { +type Contribs struct { Tags map[string]TagInfo `json:"tags"` Contributions []Contribution `json:"contributions"` } @@ -29,14 +31,41 @@ type Contribution struct { Desc string `json:"desc"` } -func ReadPlan(filename string) (Plan, error) { +func ReadContribs(filename string) (Contribs, error) { bs, err := os.ReadFile(filename) if err != nil { - return Plan{}, err + return Contribs{}, err } - var ret Plan + var ret Contribs if err := yaml.UnmarshalStrict(bs, &ret); err != nil { - return Plan{}, err + return Contribs{}, err + } + return ret, nil +} + +type Upstream struct { + URLs []string `json:"urls"` + Name string `json:"name"` + Desc string `json:"desc"` +} + +func ReadUpstreams(filename string) ([]Upstream, error) { + bs, err := os.ReadFile(filename) + if err != nil { + return nil, err + } + var ret []Upstream + if err := yaml.UnmarshalStrict(bs, &ret); err != nil { + return []Upstream{}, err + } + for i := range ret { + if ret[i].Name == "" { + u, err := url.Parse(ret[i].URLs[0]) + if err != nil { + return nil, err + } + _, ret[i].Name = path.Split(path.Clean(u.Path)) + } } return ret, nil } @@ -49,6 +78,10 @@ func MarkdownToHTML(md string) (template.HTML, error) { return template.HTML(html.String()), nil } +var githubProjects = map[string]string{ + "flori/json": "ruby-json", +} + func main() { if err := mainWithError(); err != nil { fmt.Fprintf(os.Stderr, "%s: error: %v\n", os.Args[0], err) @@ -59,19 +92,39 @@ func main() { //go:embed plan.html.tmpl var embedPlanHTMLTmpl string -var tmpl = template.Must(template.New("plan.html"). - Funcs(template.FuncMap{ - "md2html": MarkdownToHTML, - }). - Parse(embedPlanHTMLTmpl)) - func mainWithError() error { - plan, err := ReadPlan("plan.yml") + contribs, err := ReadContribs("contribs.yml") + if err != nil { + return err + } + upstreams, err := ReadUpstreams("upstreams.yml") if err != nil { return err } + tmpl := template.Must(template.New("plan.html"). + Funcs(template.FuncMap{ + "md2html": MarkdownToHTML, + "getUpstream": func(c Contribution) Upstream { + // First try any of the documented upstreams. + for _, cURL := range c.URLs { + for _, upstream := range upstreams { + for _, uURL := range upstream.URLs { + prefix := uURL + if !strings.HasSuffix(prefix, "/") { + prefix += "/" + } + if cURL == uURL || strings.HasPrefix(cURL, prefix) { + return upstream + } + } + } + } + return Upstream{URLs: []string{c.URLs[0]}, Name: "???"} + }, + }). + Parse(embedPlanHTMLTmpl)) var out bytes.Buffer - if err := tmpl.Execute(&out, plan); err != nil { + if err := tmpl.Execute(&out, contribs); err != nil { return err } if err := os.WriteFile("plan.html", out.Bytes(), 0666); err != nil { diff --git a/plan.html.tmpl b/plan.html.tmpl index d1d1696..70f7720 100644 --- a/plan.html.tmpl +++ b/plan.html.tmpl @@ -12,6 +12,9 @@ font-family: sans-serif; } + * { + box-model: border-box; + } kbd, code, samp, tt, pre { background: #DDDDFF; } @@ -34,12 +37,63 @@ article { border: solid 1px #333333; border-radius: 1em; - padding: 0.5em 2em; margin: 0.5em; } + div > p:first-child { + margin-top: 0; + } + div > p:last-child { + margin-bottom: 0; + } + + /* tags */ + article.tag { + padding: 0.5em 2em; + } article.tag > h2 { - margin: 0; - margin-left: -1em; + margin: 0 0 0.25em -1em; + } + + /* contribs */ + article.contrib { + display: grid; + grid-template-columns: 25% 75%; + padding: 0; + overflow: hidden; + } + article.contrib > div { + padding: 0.5em; + } + article.contrib div.contrib-upstream-name { + grid-row: 1 / 3; + grid-column: 1; + text-align: center; + background-color: #DDDDFF; + border-right: solid 1px #8D8DA6; + font-weight: bold; + padding-top: 1em; + } + article.contrib div.contrib-upstream-desc { + grid-row: 3; + grid-column: 1; + background-color: #DDDDFF; + border-top: solid 1px #8D8DA6; + border-right: solid 1px #8D8DA6; + } + article.contrib div.contrib-urls { + grid-row: 1; + grid-column: 2; + padding-bottom: 0; + } + article.contrib div.contrib-tags { + grid-row: 2; + grid-column: 2; + padding-top: 0; + } + article.contrib div.contrib-desc { + grid-row: 3; + grid-column: 2; + border-top: solid 1px #8D8DA6; } @@ -57,7 +111,10 @@

... by contributing...

{{- range $contrib := .Contributions }} + {{ $upstream := $contrib | getUpstream }}
+
{{ $upstream.Name }}
+
{{ $upstream.Desc | md2html }}
{{- range $url := $contrib.URLs }} {{ $url }}
diff --git a/plan.yml b/plan.yml deleted file mode 100644 index b576bb4..0000000 --- a/plan.yml +++ /dev/null @@ -1,113 +0,0 @@ -tags: - docs: - prettyName: Documentation - desc: | - I'm working to improve documentation for GNU/Linux, but more - than that I'm working to improve the forms of documentation that - more skilled technical writers might be afraid or incapable of - working on: `--help` text, generated documentation, and auditing - documentation against the source code to make sure that it is - accurate and complete. - ARM: - prettyName: ARM support - desc: | - Not that folks can't use GNU/Linux on ARM (obviously, the - Raspberry Pi has been a huge success), but there's still a lot - more friction to using GNU/Linux on ARM compared to x86. I'm - working on that. - GI: - prettyName: GObject Introspection - desc: | - GObject Introspection (which is a terrible name for what it is, - btw) is a cross-(language-runtime) object system. GObject was - an object system for C that game out of GTK+, and then GObject - Introspection was created as a way to specify the ABI for - working with an object, so that GObjects could be used from - other languages. I think that GObject Introspection is a really - cool technology that can be the basis of reducing friction - between languages, but it needs better/more-ubiquitous tooling. - -contributions: - - urls: [https://github.com/flori/json/pull/567] - tags: [Ruby, JSON, SoftwareFreedom] - desc: | - Ruby's standard JSON Gem (which comes bundled with the core Ruby - distribution!) contains code that is not Free under the FSF's - definition, not Open Source under the OSI's definition, and not - GPL-compatible. This has coused much consternation among folks - who care about any of those 3 things. - - This PR replaces that non-Free code with Free code, removing - friction for Ruby users on GNU/Linux distros that care about - those 3 things. - - urls: [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/merge_requests/328] - tags: [mkinitcpip, ARM] - sponsored-by: Umorpha Systems - desc: | - The `mkinitcpio` tool generates init-ramdisk images to boot - GNU/Linux systems. To do that it needs to know the version - number of the Linux kernel that it is generating an image for; - the normal way that it knows this is to sniff the version number - from the kernel file. However, it fails to sniff the version - number from ARM zImage kernels, which means that Arch Linux ARM - and Parabola for ARM need to resort to hacks to get mkinitcpio - to work right. - - This PR removes that friction by teaching mkinitcpio to - understand ARM zImage files. - - urls: [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/merge_requests/277] - tags: [mkinitcpio, SecureBoot] - sponsored-by: Umorpha Systems - desc: | - One of the things going on in the secure-boot world is moving - toward "Unified Kernel Images" (UKI), which are when the kernel - and the init-ramdisk are bundled together into a single file to - reduce the risk of a compromised init-ramdisk being able to - compromise a secured kernel. The `mkinitcpio` tool generates - init-ramdisk images, and this PR reduces friction when using - `mkinitcpio` to generate them as UKI. - - urls: - - https://mailman.astron.com/pipermail/file/2024-April/001335.html - - https://github.com/file/file/commit/cf139abf35d07ebfd0c3edcab2fc400a211c0fbb - tags: [file, ARM] - desc: | - The `file` tool sniffs a file to tell you about the file's - format. This PR improves its ability to detect information - about Linux kernel ARM zImage files. - - urls: - - https://mailman.astron.com/pipermail/file/2024-March/001327.html - - https://github.com/file/file/commit/3b92878ee277a6b6c0a37429e9edf5e5b55fcdd4 - tags: [file, docs] - desc: | - The `file` tool sniffs a file to tell you about the file's - format. To do this, it reads a "magic" file that describes the - magic numbers that it might see in a file. This PR fixes a - mistake in the `magic(5)` manual for writing such files. - - urls: [https://github.com/diamondburned/gotk4/pull/140] - tags: [Go, GI, docs] - desc: | - gotk4 is a project that burries the lede: yes, it is a set of Go - bindings to GTK 4.0. But (IMO) more interestingly, - `./gir/cmd/gir-generate` is a tool for generating Go bindings to - GObject Introspection (GI) libraries from the `.gir` files - describing the library. I'm working to improve that tool. - - In particular, the not-quite-markdown format that `.gir` files - use for documentation is under-specified and hard to parse. - Right now I'm focusing on how to handle that, so that we can - have top-notch language-specific documentation for GI libraries. - - This PR is laying the groundwork for the new parser. - - urls: - - https://lists.ozlabs.org/pipermail/linux-erofs/2023-November/009765.html - - https://github.com/erofs/erofs-utils/commit/f528b82ffbcb15484a7195c1a1d08ece0ff67350 - - https://github.com/erofs/erofs-utils/commit/197e3294bcdf93f37d12989cd830a33c055b1a53 - - https://github.com/erofs/erofs-utils/commit/f97311883337eb7e0ded55e60995e6599eba73e5 - tags: [EroFS, docs] - sponsored-by: Umorpha Systems - desc: | - EroFS is the Enhanced Read-Only File System, a successor to - SquashFS. This patchset improves the `--help` documentation and - man-pages the EroFS userspace tools, and reduces friction by - having `fsck.erofs` accept common command line flags that fsck - implementions for other filesystems take. diff --git a/upstreams.yml b/upstreams.yml new file mode 100644 index 0000000..ee9c5cf --- /dev/null +++ b/upstreams.yml @@ -0,0 +1,29 @@ +- urls: [https://github.com/flori/json] + name: ruby-json + desc: | + Ruby's standard JSON gem (which comes bundled with the core Ruby + distribution!). +- urls: [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio] + desc: | + The `mkinitcpio` tool generates init-ramdisk images to boot + GNU/Linux systems. +- urls: + - https://www.darwinsys.com/file/ + - https://mailman.astron.com/pipermail/file/ + - https://github.com/file/file + desc: | + The `file` tool sniffs a file to tell you about the file's + format. +- urls: + - https://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git + - https://github.com/erofs/erofs-utils + desc: | + EROFS is the Enhanced Read-Only File System, a successor to + SquashFS. +- urls: [https://github.com/diamondburned/gotk4] + desc: | + gotk4 is a project that burries the lede: yes, it is a set of Go + bindings to GTK 4.0. But (IMO) more interestingly, + `./gir/cmd/gir-generate` is a tool for generating Go bindings to + GObject Introspection (GI) libraries from the `.gir` files + describing the library. -- cgit v1.2.3-2-g168b