voting: honor system approval voting, add +1 on questions you like --- Jgart: Where is everyone --- WhereisEveryone # where is everyone is a small guix community whereis.みんな # show website/src, git, lists, todo, builds, man # thank dhruvin where is everyone? irc.libera.chat/#whereiseveryone Guix 'R Us 480 packages work-tre 13 contributors Attila Lendvai Bird Dhruvin Gandhi Disseminate Dissent Fabio Natali Julien Lepiller Matt Raghav Gururajan Stephen Paul Weber florhizome jgart paladhammika southerntofu bags.whereis.みんな # thank donotshake Meetups work-tre # First Packaging Meetup: February 2021 # First Documentation Meetup: December 2021 voting: honor system approval voting, add +1 on questions you like Guided Questions for the Session - commit style? (+1) - how should we better document the meetups? - what can be better about whereiseveryone website? - What do you think of the upstreaming from guixrus approach? - when are we going to rewrite the guix daemon in Rust? (+1) + : why not in guile?? + : It's a joke, no one around Guix really likes Rust - : let's ban Rust :D - : We can't, GTK depends on it. We should rewrite Rust in C++, though. - : lmao + : they still want to rewrite it and I am interested in that discussion, not the language choice. + : Rewriting it in Guile would be interesting for Guix users, mainly because we don't really want to touch scary C++. + : this is why I think we should discuss this, there are more concerns to be aware of.. + : Which of those concerns would Rust address, though? Writing it in low-level Guile would still make many people not touch it, but perhaps there would be more experts if everything was the same language. + : bah who cares about rust, that is not my concern. + : That's why you missed the joke ^^" + : I don't like rust because it is complicated monolithic and not bootstrappable or standardized. However rewriting the nix daemon, regardless of language, means we need to think about a ton of things and I think that is an important discussion. + : True, but you're not going to do it in 10~15min in a Q&A. Even for a language as widely accepted among Guix as Guile, there are very many architectural concerns to take into account, which would spawn several guix-devel threads. + : if the discussion is too big then the discussion about how we can have the discussion is not. - would you like to try etherpad and mumble for documentation meetups? (+1) - is jami ready? can we try jami for meetups? (+2) What happened to meet.jit.si? - would you like to work on a requirements.txt/pyproject.toml to manifest parser? - what do you think of having guix internals meetups? (+2) - how can we work on packages together? (+1) - what would you like to discuss? - do you like big blue button or something else? - how would you like to attribute yourself in meetup commits? - what are you currently packaging for Guix? (+1) - should we communicate beforehand over irc to discuss future meetup plans? - would you like to collaborate on stuff during the month before the official meetups? (+1) - how can we facilitate upstream contributions for new users? - foo? bar? cons? - spam, ham & eggs? THNX https://git.sr.ht/~whereiseveryone/slides V ' --- Blake: Guile Docs Session --- * Principals 1) [X] Words are data - Titles should explicate section contents. - Technical writing requires consistency of presentation across entries. Pros: samplet: Consistency aids learning and memorization. Cons: missing the "how" lilyp: Okay, makes sense ilmu: why pro/con metatheory? ilmu: so the reason I disagree with the pro/con metatheory is because I agree with all the principles but they are stated decleratively for us to act on so we should state our how. ilmu: I wrote a "how" for each thing. The how for this one is datalisp. - blake: got it, thanks for the feedback samplet: In terms of "how", I think it will get easier over time. Agreeing on terms, etc. might be hard at first. 2) [X] Showing > Telling - In the core reference, we should aim for an executable example for every 1-6 lines of written word. - Sections require zap: +1, I've seen newbies strugling to understand the manual and complaining about the lack of examples. But 1-6 is probably high bar. Christian: +1 I totally agree with blake2b, I tried to teach myself Guile at least twice and found the documentation very confusing Yeah sounds as aswome idea :) samplet: TBH, I found the 'match' example in the talk to be a bit much, but I agree with the general idea. Maybe less examples that are more pointed. I think I mostly didn't like the structure of the examples particularly, like matching on floats vs. intergers is not that insightful. To be clear, I'm onboard! The REPL thing + modules at the top is a great idea, BTW. +1 how: (tl;dr basically I'm saying `info` needs an overhaul). lilyp: you could do this with anchors, e.g. info '(guile)record-some-example', agreeing with blake Executable commands indexed in menus. That's literally showing, press enter to execute command. To make it more guile specific: you are explaining some concept like recursion, now you can have different examples (and expressive graduation) indexed in a menu of examples. Pick one to open the code and a repl that has the definition open... This is the kind of data the menu should carry 3) [X] Expressive graduation - Example terms should be chosen to emphasize procedure application across applicable data types, graduating in stages to more advanced data structures that one can fairly obviously follow the current example if they understand the previous example. 4) [ ] The particular presumes the general - If a procedure is commonly used in tandem with other procedures, this should be documented. How: Semantic web. 5) [ ] Software is a discourse - Push popular community practices to the front: (srfi srfi-1) (srfi srfi-9) (ice-9 match) etc. Try not to partition them. How: Sybil resistance is the big problem in general but we also don't have a sufficient forum system to begin with so we don't even have that problem. Difficult problem. 6) [ ] Theres nothing outside the text - Assume nothing, don't assume the reader knows anything beyond the core established idioms. zap: There is a bunch of functional programming jargon that is not commonly known outside fp - Consequence: always declare (use-modules ...) at the top of any page that uses them How: Manage snippets individually and compose the documentation from these snippets. 7) [ ] Birds of a feather flock together - Related procedures should be placed in reasonable range How: Remixing the different snippets of explanation into different presentations (re: module theory of documentation from presentation) * Changes 1: Guile Tutorials 1) [ ] Hello Guile -> Quick: A Speedy Tour of Guile lilyp: Objection, "Hello, world" is a well established idiom roptat: I like explicit jpoiret: I think explicit is good as well, I've always been confused by the first few section names lilyp: I'd rename Hello Scheme, but keep a "Hello world"-style thing in the front (perhaps a shorter one) *** roptat: or make the current title explicit: "Hello, Guile: a quick tour of guile" lilyp: SGTM 2) [ ] Hello Scheme -> Understanding Scheme jpoiret: If i'm new to Guile/Scheme, that doesn't tell me what this is about. eg, what is Scheme, why should I care, and what is in it? lilyp: SGTM lilyp: @jpoiret: Perhaps "A quick introduction to Scheme" jpoiret: Right, but that still doesn't tell me why I should read this compared to "A quick tour of Guile" lilyp: Hmm, "Basics of Scheme Programming" – we're laying out groundwork for the rest jpoiret: Do we really need to mention Scheme here? i feel this would confuse newcomers, and people who know Scheme will know that Guile is a scheme anyways. Purely from a pragmatic pov. lipklim: Guile (Scheme) Concepts jpoiret: Guile concepts from Scheme? Maybe, a sort of "What even is a Scheme [dialect]?" +3 [dialect] -> Depends on what kind of people we want to target, somebody who knows what a Lisp is and used one? Or somebody that is coming from C-likes and hasn't heard of it. lilyp: We should introduce the reader to the concept that Guile is a Scheme early on. bikeshedding time 3) [ ] Programming in Scheme -> The Guile Toolshed lilyp: what's a toolshed? (conflicts with #1 imo) roptat: I don't like toolshed either, maybe because I'm not a native English speaker, I can't imagine what that means. 4) [ ] Programming in C -> Programming with C and Guile Why merging the two? "Interfacing with libguile from C"? "Using C and Guile in tandem?" lipklim: For C related stuff we can have separate index, referencing every section that concernes C. Christian: I agree with ^^^, when I'm just starting out, I'm not interested in embedding C into Guile or vice versa. lilyp: +1 for splitting libguile API into a completely separate section/manual roptat: "embedding Guile in C", maybe split "embedding Guile in C" and "Extending Guile with C"? I was thinking both have a different audience 5) [ ] Pack all of the above into a section titled "The Guile Tutorials" +1 lipklim: MIT/GNU Scheme split manual in two part: One about how to interact with program (mit-scheme) https://www.gnu.org/software/mit-scheme/documentation/stable/mit-scheme-user/ And one about data types etc. * Changes 2: API Reference Refactoring the documentation layout 1) [ ] Deprecation, The SCM Type, Initialization & Snarfing Macros should all be packed into API Overview lilyp: Why "deprecation" at the very start? Should it not be at the end of (1)? lipklim: lilyp: it's current state, look at the manual. It's the secend subsection now. lilyp: Okay jpoiret: Maybe create a new separation "Guile for the Guile programmer" vs "Guile for the C Embedder". Right, there's a lot of C things inside the "pure-Guile" docs. 2) [ ] +Binding Constructs & Utility functions+ should be placed in procedures lilyp: binding constructs are syntax, not procedures. For utility procedures, okay. I think "binding constructs" could be explained somewhat in "Understanding Scheme" or however it is called then 3) [ ] POSIX & Expect should be moved to I/O, to be renamed I/O & Systems Interfaces lilyp: Perhaps "System Interfaces" with subsection I/O. jpoiret: A novice programmer wouldn't think to find I/O inside Systems Interfaces. lilyp: Separate basic I/O (display/format) from system specifics like POSIX 4) [ ] LALR & Peg should be packed into a single section called "Parsers" lilyp: Sounds Good To Me roptat: +1 5) [ ] FFI, Foreign Objects & Smobs packed into a section called "FFI and Foreign Objects" lilyp: We need to deprecate smobs already :P roptat: shouldn't that be in the programming in C section? lilyp: FFI/Foreign objects handles scheme side too, but there's def some overlap Perhaps the last section (of the API overview) could be "Legacy things that we carry on for consistency" Christian: agree with this ^^^, preferably with pointers to "how things are done nowadays". 6) [ ] ~Utility Functions~ -> Predicates, Sorting & Copying Utility Functions: Predicates, Sorting, Copying... 7) [ ] ~Expect~ -> Expect: Command Line Handling lilyp: SGTM 8) [ ] ~Initialization~ -> Initialization for Embedded Guile * Changes 3: Guile Modules ... 1) [ ] Discourse: move Pattern Matching, SRFI-1 & SRFI-171, and others into a new section called "Functional Programming" 2) [ ] Birds: move SXML & SXML-match into Web 3) [ ] Birds: move getopt-long to Procedures in API 4) [ ] Birds: pack R6/R7RS into a single RnRS section lilyp: SGTM. 5) [ ] Birds: move Pretty Printing & Formatted Output to a group called Printing & Formating 6) [ ] Birds: move File Tree Walk & Buffered Input into new IO/System in API 7) [ ] Birds: Put Queues in Datatypes API 8) [ ] Birds: move Curried Definitions to binding constructs in API 9) [ ] Discourse: move Readline support last 10) [ ] Legacy: move SLIB, scsh, and streams to a 'legacy' section. * API Before * API Overview * Deprecation * The SCM Type * Initialization * Snarfing Macros * Data Types - Booleans - Numerical data typs - Characters - Character sets - Strings - Symbols - Keywords - Pairs - Lists - Vectors - Bit Vectors - Bytevectors - Arrays - Records Oververview - SFRI-9 Records - Records - Structures - Dictionary Types - Association Lists - VHashes - Hash tables * Procedures - Lambda - Primitive Procedures - Compiled Procedures - Optional Arguments - Case-Lambda - Higher-order Functions - Procedures with Setters - Inlinable Procedures * Macros:: Extending the syntax of Scheme. * Utility Functions:: General utility functions. * Binding Constructs:: Definitions and variable bindings. * Control Mechanisms:: Controlling the flow of program execution. * Input and Output:: Ports, reading and writing. * Regular Expressions:: Pattern matching and substitution. * LALR(1) Parsing:: Generating LALR(1) parsers. * PEG Parsing:: Parsing Expression Grammars. * Read/Load/Eval/Compile:: Reading and evaluating Scheme code. * Memory Management:: Memory management and garbage collection. * Modules:: Designing reusable code libraries. * Foreign Function Interface:: Interacting with C procedures and data. * Foreign Objects:: Defining new data types in C. * Smobs:: Use foreign objects instead. * Scheduling:: Threads, mutexes, asyncs and dynamic roots. * Options and Config:: Configuration, features and runtime options. * Other Languages:: Emacs Lisp, ECMAScript, and more. * Internationalization:: Support for gettext, etc. * Debugging:: Debugging infrastructure and Scheme interface. * Code Coverage:: Gathering code coverage data. * API After * [ ] API Overview + ~Deprecation~ + ~The SCM Type~ + ~Initialization~ =with C= + ~Snarfing Macros~ =for C= * Data Types - Booleans - Numerical data typs - Characters - Character sets - Strings - Symbols - Keywords - Pairs - Lists - Vectors - Bit Vectors - Bytevectors - Arrays - Records Oververview - SFRI-9 Records - Records - Structures - Dictionary Types - Association Lists - VHashes - Hash tables + ~Queues~ * [ ] Procedures ~birds of a feather~ - Lambda + ~Binding Constructs~ - Primitive Procedures - Compiled Procedures - Optional Arguments - Case-Lambda - Higher-order Functions - Procedures with Setters - Inlinable Procedures + ~Utility Functions~ + Change name to =Predicates, Sorting, and copying= ~words=data~ + ~getopt-long~ + [ ] Module System ~discourse~ + [ ] Functional Programming ~discourse~ - Compose - Pattern Matching (ice-9 match) - Fold, Unfold and Map (SRFI-1) - Reducers & Transducers (SRFI-171) - (...) and so on * Macros * Control Mechanisms * [ ] I/O & Systems interfaces - Ports - Binary i/o - Encoding - Textual - Simple Textual Output - Buffering - Random Access - Line Oriented and Delimited Text - Default Ports - Types of Ports - Venerable port Interfaces - Using ports from C - implementing new port types in C - Non-blocking I/O - Handling Unicode byte order marks + ~POSIX interface~ + ~Expect: CLI Handling~ * Regular Expressions + [ ] Parsing ~birds of a feather~ - LALR(1) Parsing - PEG Parsing * Read/Load/Eval/Compile * Memory Management * [ ] FFI, Foreign Objects, Smobs ~birds~ - FFI - Foreign Objects - Smobs Use foreign objects instead. * Scheduling * Options and Config * Other Languages * Internationalization * Debugging * Code Coverage -- end Blake Session --