5 ms·

Git manpage generator

95 points by orkoden 13y ago

ozh 13y ago
Fun. Unfortunately, I think it's a bad sign when random mambo-jumbo generated by a Markov chain script looks so much like the real stuff...
- ygra 13y ago
  Markov chains help a lot in making the output look like the real stuff, that's kinda their purpose in this case. Heck, there have been automatically-generated conference papers that have been accepted and went through peer review (although this might tell a lot about that process, too ...). git manpages are apparently full of very git-specific terminology and quite dense. I would guess the same model applied to the J documentation would be equally unreadable for the uninitiated. If the source material was more readable and easier to grasp the automatically-generated versions would reflect that (to some degree, until it's obvious that's nonsense).
  - Silkebacon 13y ago
    The generator doesn't use markov chains, it's grammar-based similar to the Dada Engine which powers the postmodernism generator. There's a link to a markov chain based generator in the footer, check it out, it's pretty funny and a lot more random.
    - ygra 13y ago
      I stand corrected on that point, then. But still, I guess it's no surprise that something tailored to look/sound like something else looks/sounds like that something else ;-)
  - dtech 13y ago
    > Heck, there have been automatically-generated conference papers that have been accepted and went through peer review Those papers were used to prove that those conferences weren t actually peer reviewed.
jordigh 13y ago
I wonder, since this is an obvious parody of the sorry state of git's manpages, do people find Mercurial's manpages any easier to read? http://www.selenic.com/mercurial/hg.1.html http://www.selenic.com/mercurial/hg.1.html
- DougBTX 13y ago
  Mercurial's seem to assume less knowledge, the bisect pages are a good example. Mercurial bisect: This command helps to find changesets which introduce problems. Git bisect: Find by binary search the change that introduced a bug Someone could happily use Mercurial bisect without knowing that it is doing a binary search. The Mercurial docs also get into simple examples before explaining all the options, while the git docs list all of the options first, which presumably could scare people away who are just after simple usage.
  - jimktrains2 13y ago
    On the flip side the git docs provide more useful information about what it's actually going to do to help you, not just in general how it'll help you.
    - Xylakant 13y ago
      actually, I don't care if git uses binary search or any other algorithm. I care that it helps me find bugs fast. There could be a "if you're interested in the tech" part in the git manpages that adds the information for the people that want or have to know, but I, as a user, couldn't care less - I can't change it anyways.
      - edwintorok 13y ago
        What matters is that 'git bisect' helps you find the bug in a significantly smaller number of steps than trying all revisions by hand. The manpage should definitely either mention the algorithm (binary search), or the reason why you would use it in the first place (it significantly reduces the number of steps until you find a bug, versus trying all commits). Note that the 'hg bisect' still fits this requirement, because its name hints at the algorithm. If it only mentioned that it finds the changeset introducing a bug, without saying how, or that it does it efficiently what would be the reason to use the command at all?
Dorian-Marie 13y ago
I find it really accurate to my experience with Git man pages, e.g: https://www.kernel.org/pub/software/scm/git/docs/ https://www.kernel.org/pub/software/scm/git/docs/
pekk 13y ago
and yet I still switched to Git, knowing all this, and don't regret it, because it gives me enough power to fit my workflows rather than me serving my VCS all day. There are now a large number of friendly ways to learn git, if you don't like the man pages then don't use them. It's not exactly uncommon for man pages to have technical material in them
fish2000 13y ago
I did not think a random-thing-generator could possibly make me laugh again, but for me `git-shoot-subtree` was the undeniable breaking point.
nandhp 13y ago
I wish it had permalinks.
- Silkebacon 13y ago
  That's a great idea. I'll see what I can do! Edit: Just added the permalink feature, thanks for the tip!
jvilk 13y ago
I made a (very childish) bookmarklet to make it more fun :) http://people.cs.umass.edu/~jvilk/bookmarklet.html http://people.cs.umass.edu/~jvilk/bookmarklet.html (The "javascript:" link for the bookmarklet is on this page) Click it when you're on a Git manpage, either legitimate or generated.

95 points by orkoden 13y ago

ozh 13y ago

Fun. Unfortunately, I think it's a bad sign when random mambo-jumbo generated by a Markov chain script looks so much like the real stuff...

ygra 13y ago
Markov chains help a lot in making the output look like the real stuff, that's kinda their purpose in this case. Heck, there have been automatically-generated conference papers that have been accepted and went through peer review (although this might tell a lot about that process, too ...). git manpages are apparently full of very git-specific terminology and quite dense. I would guess the same model applied to the J documentation would be equally unreadable for the uninitiated. If the source material was more readable and easier to grasp the automatically-generated versions would reflect that (to some degree, until it's obvious that's nonsense).
- Silkebacon 13y ago
  The generator doesn't use markov chains, it's grammar-based similar to the Dada Engine which powers the postmodernism generator. There's a link to a markov chain based generator in the footer, check it out, it's pretty funny and a lot more random.
  - ygra 13y ago
    I stand corrected on that point, then. But still, I guess it's no surprise that something tailored to look/sound like something else looks/sounds like that something else ;-)
- dtech 13y ago
  > Heck, there have been automatically-generated conference papers that have been accepted and went through peer review Those papers were used to prove that those conferences weren t actually peer reviewed.

jordigh 13y ago

I wonder, since this is an obvious parody of the sorry state of git's manpages, do people find Mercurial's manpages any easier to read? http://www.selenic.com/mercurial/hg.1.html http://www.selenic.com/mercurial/hg.1.html

DougBTX 13y ago
Mercurial's seem to assume less knowledge, the bisect pages are a good example. Mercurial bisect: This command helps to find changesets which introduce problems. Git bisect: Find by binary search the change that introduced a bug Someone could happily use Mercurial bisect without knowing that it is doing a binary search. The Mercurial docs also get into simple examples before explaining all the options, while the git docs list all of the options first, which presumably could scare people away who are just after simple usage.
- jimktrains2 13y ago
  On the flip side the git docs provide more useful information about what it's actually going to do to help you, not just in general how it'll help you.
  - Xylakant 13y ago
    actually, I don't care if git uses binary search or any other algorithm. I care that it helps me find bugs fast. There could be a "if you're interested in the tech" part in the git manpages that adds the information for the people that want or have to know, but I, as a user, couldn't care less - I can't change it anyways.
    - edwintorok 13y ago
      What matters is that 'git bisect' helps you find the bug in a significantly smaller number of steps than trying all revisions by hand. The manpage should definitely either mention the algorithm (binary search), or the reason why you would use it in the first place (it significantly reduces the number of steps until you find a bug, versus trying all commits). Note that the 'hg bisect' still fits this requirement, because its name hints at the algorithm. If it only mentioned that it finds the changeset introducing a bug, without saying how, or that it does it efficiently what would be the reason to use the command at all?

Dorian-Marie 13y ago

I find it really accurate to my experience with Git man pages, e.g: https://www.kernel.org/pub/software/scm/git/docs/ https://www.kernel.org/pub/software/scm/git/docs/

pekk 13y ago

and yet I still switched to Git, knowing all this, and don't regret it, because it gives me enough power to fit my workflows rather than me serving my VCS all day. There are now a large number of friendly ways to learn git, if you don't like the man pages then don't use them. It's not exactly uncommon for man pages to have technical material in them

fish2000 13y ago

I did not think a random-thing-generator could possibly make me laugh again, but for me `git-shoot-subtree` was the undeniable breaking point.

nandhp 13y ago

I wish it had permalinks.

Silkebacon 13y ago
That's a great idea. I'll see what I can do! Edit: Just added the permalink feature, thanks for the tip!

jvilk 13y ago

I made a (very childish) bookmarklet to make it more fun :) http://people.cs.umass.edu/~jvilk/bookmarklet.html http://people.cs.umass.edu/~jvilk/bookmarklet.html (The "javascript:" link for the bookmarklet is on this page) Click it when you're on a Git manpage, either legitimate or generated.