One key benefit of putting up an own server is that there are no limitations on file types and much fewer restrictions on what kind of content you can create.
For serving static files, I can (and have) lived a long time with one of the "free hoster" sites -- from times before Github Pages or S3 were a thing I guess, today I'd go for Github Pages.
A key advantage of moving to an own server was that I can enable the odd feature or technology any time. E.g. most recently I wanted to have some "private" subspace with fancy authentication and it was easy to add with proper access to the server config.
Unlike Framesets I think XML includes were never really supported in many browsers (or even any major browsers)?
I still like to use them occasionally but it incurs a "compilation" step to evaluate them prior to handing the result of this compilation to the users/browsers.
As it happens, the major browsers still can do XML 'includes' to some extent, since by some miracle they haven't torn out their support for XSLT 1.0. E.g. this outputs "FizzBuzz" on Firefox:
Yep, and this can be used to e.g. make a basically static site template and then do an include for `userdata.xml` to decorate your page with the logged in user's info (e.g. on HN, adding your username in the top right, highlighting your comments and showing the edit/delete buttons, etc.). You can for example include into a variable `<xsl:variable name="myinfo" select="document('userdata.xml')"/>` and then use it in xpath expressions like `$myinfo/user/@id`. Extremely simple, good for caching, lightweight, very high performance. Easy to fail gracefully to the logged out template. You basically get your data "API" for free since you're returning XML in your data model. I will never understand why it didn't take off.
XML includes are blocking because XSL support hasn't been updated for 25 years, but there's no reason why we couldn't have it async by now if resources were devoted to this instead of webusb etc.
You'd better not jinx it: XSL support seems like just the sort of thing browser devs would want to tear out in the name of reducing attack surface. They already dislike the better-known SVG and never add any new features to it. I often worry that the status quo persists only because they haven't really thought about it in the last 20 years.
I’ve used XSLT in anger - I used it to build Excel worksheets (in XML format) using libXSLT. I found it very verbose and hard to read. And Xpath is pretty torturous.
I wish I could have used Javascript. I wish Office objects were halfway as easy to compose as the DOM. I know a lot of people hate on Javascript and the DOM, but it’s way easier to work with than the alternatives.
Isn't this what proper framesets (not iframes) were supposed to do a long time ago (HTML 4?). At least they autoexpanded just fine and the user could even adjust the size to their preference.
There was a lot of criticism for frames [1] but still they were successfully deployed for useful stuff like Java API documentation [2].
In my opinion the whole thing didn't stay mostly because of too little flexibility for designer: Framesets were probably well enough for useful information pages but didn't account for all the designers' needs with their bulky scrollbars and limited number of subspaces on the screen. Today it is too late to revive them because framesets as-is wouldn't probably work well on mobile...
Issue with frame set was way more fundamental: No deep linking, thus people coming via bookmarks or Google (or predecessor) were left on a page without navigation, which people then tried working around with JavaScript, which never gave it a good experience.
Nowdays it is sometimes the other way around: Pages are all JavaScript so no good experience in the first place. I have encountered difficulty trying to get a proper “link” to something multiple times. Also, given that Browsers love to reduce/hide the address bar I wonder if it is really still that important a feature.
Of course "back then" this was an important feature and one of the reasons for getting rid of frames :)
It may not be perfect for all cases (e.g. if some sort of dependency is linked but not present in the source tree it is naturally not really accounted for by Debian copyright files) but then there is always the options of either adding copyright information to every source code file (I don't like that style for redundancy but it is for sure a very clear way to do it) or to hand-craft a human-readable variant similar to the Debian approach but less formally.
In any case it seems that nothing is new aobut this and developers working with FOSS software should very well be aware of these concepts.
I usually try to avoid the "makefile effect" by learning the technolgoy I use reasonably frequently (like e.g. Makefiles, Shell Scripts, ...).
However, despite the fact that I used to use LaTeX very much, I always copy-pasted from a template. It is even worse with beamer presentations and TikZ pictures where I would copy-paste from a previous presentation or picture rather than a template.
For TikZ I am pretty sure that the tool is inherently complex and I just haven't spent enough time to learn it properly.
For LaTeX I have certainly spent enough time on learning it so I wonder whether it might be something different.
In my opinion it could very well be a matter of “(in)sane defaults”. Good tools should come with good defaults. However, LaTeX is not a good tool wrt. this metric, because basically all my documents start something like
Most of this is to get some basic non-ASCII support that is needed for my native tongue or enable some sane defaults (A4 paper, microtype...) which in a modern tool like e.g. pandoc/markdown may not be needed...
Hence the purpose of copy-pasing the stuff around is often to get good defaults which a better tool might give you right out of the box (then without copy/paste).
Copy-pasting itself is not bad per se. What's bad is copy-pasting without understanding the why and how.
For LaTeX I also copy-paste a whole lot from older files, but I don't feel bad because (a) I wrote these files before, (b) I know exactly what each line is doing, (c) I understand why each line is needed in the new doc.
I wrote a relatively large amount of TikZ code earlier in my life (basically used it as a substitute for Illustrator) and for this library in particular, I think it just has so much syntax to remember that I cannot keep it all in my brain for ever. So I gladly copy from my old TikZ code.
\usepackage[utf8]{inputenc} now is the default, at least; you don't need to include it anymore. And diacritics work out of the box, no need to write weird incantations like G\"{o}del anymore.
I am rather ambivalent about these rules. I disagree with a lot of the individual points, but I am also sure that I have probably often written bad tutorials myself where some of the rules would have clearly helped... :)
> 5. Make code snippets copy/pasteable
I like to use the prompt to identify the language and also the user (root `#` vs. user shell `$`) to perform the action under. I advise against copying random commands off the internet especially those that run as root and may break your system (like `apt` and `--yes` together...). Of course, today, it is often assumed that you have sudo setup and then `sudo ...` is used to indicate the use of root privileges. It is an interesting convention although in my opinion this sometimes hides the actual intent.
I prefer:
# echo 3 > /proc/sys/vm/drop_caches
over
echo 3 | sudo tee /proc/sys/vm/drop_caches
The example given in the article is exactly one where attention is required: It adds a PPA as root, thereby giving "full control" to the PPA author. Never straightout copy-paste such stuff.
> 6. Use long versions of command-line flags
I am so much more used to the short versions hence I prefer `grep -RF` over `grep --dereference-recursive --fixed-strings`. Also, my go-to documentation about these commands (POSIX) doesn't even know about the long options.
I know that the advice to prefer the long options is repeated pretty often so it might just be me :)
> 7. Separate user-defined values from reusable logic
Ever followed some "enterprise-grade" software setup tutorial? Sometimes they start by assigning 20 variables to some generic values that you don't change most of the time and then go about to reference them on the next 20 pages or such making it close to impossible to know what is really going on. Also I find that for simple cases this greatly complicates the input process.
I think the example doesn't really show the difference because it has some variables (just not in shell syntax) in the code already like `YOUR-API-TOKEN`. Of course it is better to write `$API_TOKEN` rather than `YOUR-API-TOKEN`. I often prefer to see the example value in the example i.e. not `YOUR-API-TOKEN` but some real string (if feasible). In many cases I won't change a value in the beginning to see how far I get with a “known valid input”. Also, I often prefer to pattern-match some real value against what I have available, e.g. I have a key which I think could be the API key but if the format is totally different from the tutorial I may realize that this is an "app token" rather than "API key" and that I may need to get a different value if it fails to run with my input or such.
> 9. Let computers evaluate conditional logic
If dosed correctly, I think this is good advice. I'd strongly prefer the conditional boxes from the “bad” example over the “good” monster shell script command. In my opinion a tutorial shouldn't optimize for speed of execution but rather foster the understanding by the reader. There is no help if I find this post 10 years later and it helpfully outputs “ERROR: Unsupported platform” on my Debian 16 system. If the text instructions are given as in the “bad” example, I quickly realize that all of this is outdated and I should probably try with the most recent package name (example-package2) rather than meddle with some script.
> I am so much more used to the short versions hence I prefer `grep -RF` over `grep --dereference-recursive --fixed-strings`. Also, my go-to documentation about these commands (POSIX) doesn't even know about the long options.
I know that the advice to prefer the long options is repeated pretty often so it might just be me :)
It is not just you.
I also prefer short options for most “standard” commands (e.g. everything POSIX). I don’t see any value in educating readers in the long options of grep, or ls, or cat.
OTOH using long options may be useful for less common commands, or if the commands are specific to the software the tutorial is about.
Yeah, with automatic evaluation dosed correctly is key. It can quickly become a slippery slope, turning into a 100 line monstrosity supporting the most esoteric environments, like "if user is not in the sudoers group and is running offline in a dockerfile without a tty on solaris8 through pdp virtualization on apple silicon".
Some times it is better to let the user think for themselves rather than provide a "paste this magic script". If you are going to use a script, you are kindof taking away the purpose of a tutorial; to learn each individual thing step by step, not how to run another black box.
I use Firefox + uMatrix to achieve a similar setup.
One advantage of using only a script blocker in favor of a proper ad blocker is that I don't shut off reasonable ads but only the ones that do shady stuff with a lot of computation and tracking on the client PC.
uMatrix has the advantage that it additionally blocks cookies by default, making the tracking even harder.
I don't like that I have to mash some tiny buttons to set the "OK" up and also to stop it. The LED that shows that the alarm is active is also hard to read for me. Hence I tried to improve upon this in my own design. I also found a solution to avoid the backup battery, but it is probably not what the "general public" would like to have either :)
What became of "don't ask to ask" (https://dontasktoask.com/)? Although it may take some getting used to, I find it convincing that one shouldn't need to ask about whether it'd be OK to ask for short questions because the question for permissing is interrupting just as much as the actual question except that with the former it may be impossible to estimate how complex it is whereas it may be much easier to decide if the question is known.
For longer issues, could it make more sense to schedule an (online) meeting?
And on the receiving side of interruptions: Ocasionally it has helped me to just keep the "chat app" closed when I want to concentrate on something. If anyone has something urgent, they could always elevate to performing an old-style synchronous phone call, but interestingly this rarely happens with "text-chat" people :)
that's similar to the no hello movement. if you're going to ask a question over chat, just ask it, we don't need the pretend conversation around it, and by saying hello you've already interrupted me.
> * Simple markdown-like markup language with math support for my website/blog. I did it so that I get nice SVG equations that show up without things jumping around all the time while it's rendering. https://github.com/dllu/dllup
Nice design and nice page :) I was wondering whether I should post my own take which has a set of similar requirements, too, but figured that at least currently it does not give much “productivity” but is more of a free-time activity for myself.
For serving static files, I can (and have) lived a long time with one of the "free hoster" sites -- from times before Github Pages or S3 were a thing I guess, today I'd go for Github Pages.
A key advantage of moving to an own server was that I can enable the odd feature or technology any time. E.g. most recently I wanted to have some "private" subspace with fancy authentication and it was easy to add with proper access to the server config.
reply