
Argdown - Qaphqa
https://argdown.org
======
szemet
It would have been helpful to me, if the page would try to explain and "sell"
not just the tool, but the idea of argument maps too (e.g. in a few initial
paragraph).

I've met the concept of argument map for the first time, and had to google it
to gain some understanding:
[https://en.wikipedia.org/wiki/Argument_map](https://en.wikipedia.org/wiki/Argument_map)

~~~
shusson
> if the page would try to explain and "sell"

It's a specific tool for argumentation. I don't think they need to explain
what argumentation is.

~~~
derefr
Argument maps are not “a tool for argumentation”; they’re not intended to be
used in every context in which people argue. If they were, we all probably
would have heard of them already at some point, if just as “that weird thing I
see no reason to use.”

Argument maps are intended to either _analyze_ or _formalize_ the sides of an
argument, in one of two contexts:

• contexts like civic policy, where a third party (e.g. an analyst working for
a politician) wants to create an executive summary of a debate for consumption
by a policy-maker, usually by watching/reading, and then “digesting”, a lot of
arguments. (In this context, it also helps to be able to _merge_ argument
maps, efficiently unifying nodes that are semantically similar while keeping
their dissimilar children.)

• In cases of formal debate, where the goal of the debaters is, as often as
not, not for one side to dominate the other with rhetoric, but rather for
everyone to “adversarially collaborate” to _discover_ the complete shape of
the debate—to _map_ all the pros and cons—so that they can then go over the
mapped argument and judge its merits for themselves, rather than working form
the incomplete information they started with (usually just the information
held by their “side.”)

Combine these two, and you get “barristers on both sides of a court, working
_for_ a judge as analysts to help them understand both sides of a case”—as in
truth-discovering (rather than guilt-deciding) judicial systems like
Scotland’s; or as in grand juries or coroner’s inquests.

(You can also use argument maps in your personal life, if you want to be
really objective about deciding whether to believe something. But the contexts
in which there are so many good arguments on both sides that you’d get a
different answer than the one you’d get by just listening to the debate with
an open mind, would be rare. For a cute analogy, they’re “asymptotes of
discourse”: places where you’re dividing infinite evidence by infinite
evidence, and so need something more powerful than regular mental arithmetic
to get a solution.)

~~~
vincent-toups
"In cases of formal debate, where the goal of the debaters is, as often as
not, not for one side to dominate the other with rhetoric, but rather for
everyone to “adversarially collaborate” to discover the complete shape of the
debate—to map all the pros and cons—so that they can then go over the mapped
argument and judge its merits for themselves, rather than working form the
incomplete information they started with (usually just the information held by
their “side.”)"

I did formal (policy) debate and my goal was always to win. Are there forms of
formal debate which are really oriented towards sketching out a complete
argument landscape?

~~~
tempguy9999
> I did formal (policy) debate and my goal was always to win

I find this POV difficult to understand. Maybe I'm misunderstanding (and what
is "policy" debate vs plain old debate?)

. Did you want to win for a reason other than winning?

. Did you ever feel you were wrong but won anyway?

. Did anybody make you doubt your position? If so what was your response?

. My position is to find the 'truth' so if I'm shown wrong I'll accept it
quickly. Do you think this is a flawed approach compared to yours?

Not hostile, but curious, thanks.

~~~
vincent-toups
No hostility detected!
[https://en.wikipedia.org/wiki/Policy_debate](https://en.wikipedia.org/wiki/Policy_debate)

Policy debate is a formal style of competitive debate, characterized by a high
degree of "game" like behavior and, most notably, the act of making arguments
as fast as possible, so as to literally make it impossible for your opponent
to answer them all.

Mostly its a high school thing, but there are some college leagues.

To answer your questions:

\- Winning made me feel smart and cool.

\- Never, but I also don't feel I was right either, really. I mean the
relationship to the substance of the ideas in the debate is so tenuous. It
really is a kind of high speed game of conceptual chess, more than an
argument.

\- The policy debater takes up and puts down positions like tools. One round
you might make an argument you defeated in the previous round. You might argue
against your very own position.

\- As a data scientist (and a scientist and philosopher in general) I'm with
you about truth being important (as far as that goes) but policy debate is
much more about developing a facility with ideas. A certain detachment from
specific ideas is actually very important to finding the true ones, and policy
debate helps you see that.

On the other hand, it does make people cynical. I see a lot of what is wrong
with this country in my training as a debater. Its a thing taught mostly to
rich kids at private schools and it teaches them to bullshit, which is a
critical skill if you're to lord it over the plebes. The world might be better
off it we didn't know how.

My view these days is that I'm quite skeptical of strong claims made either
way and that I prefer virtue ethics, which say we should focus less on complex
schemes to understand and manipulate the world and more on our character
moment to moment.

~~~
tempguy9999
Excellent answer, very informative, thanks!

------
Qaphqa
A simple syntax (kind of Markdown) for complex argumentation, defining complex
dialectical relations between arguments. Your document is transformed into an
argument map while you are typing.

Screenshot: [http://www.argunet.org/wordpress-argunet-2/wp-
content/upload...](http://www.argunet.org/wordpress-argunet-2/wp-
content/uploads/2018/10/argdown-vscode-semmelweis-1.png)

~~~
zucker42
This site desperately needs a picture like the one you just posted on its
front page.

~~~
r00fus
I dunno, if you click [map] on one of the argdown examples, it interactively
flips to the diagram of said syntax.

I didn't find that too difficult to discover. It even seemed more interactive.

~~~
pas
True, but most people won't click on map.

~~~
Tepix
I did :-)

------
TeMPOraL
Do pro/con trees actually work in real life? I played with something like this
when using Kialo for a while, and my impression was that this technique
doesn't help much. Shoehorning everything into a pro or con is one thing,
duplication of points in many places in a tree is another.

I abandoned Kialo with a conclusion that pro/con trees don't map well to
reality; we need _graphs_ of facts and their relationships.

(Also, my gut feeling is that when you're talking about "arguments" instead of
"facts", "evidence" and probabilities, you're in business of convincing, not
truth seeking).

But that's not to diss this project. As an implementation of pro/con trees
it's excellent, and I'd prefer typing in this language a millon times more
than clicking around Kialo.

~~~
derefr
> duplication of points in many places in a tree

It _seems_ (but I might be wrong) that this syntax allows for nodes to also
reference other nodes rather than embedding them (see e.g. the third example
on the page, though it’s too trivial to tell if that’s what it’s doing for
sure.) I think they expect you to draft the argument map, then go back over it
and iteratively reduce it by manually normalizing duplicate sub-arguments into
one canonical sub-argument in one place + references to it in other places.

> Also, my gut feeling is that when you're talking about "arguments" instead
> of "facts", "evidence" and probabilities, you're in business of convincing,
> not truth seeking.

Usually the point of this kind of software (argument-mapping software) is to,
first, efficiently _capture_ an argument that exists, either as a sort of
“court stenographer” during the argument, or from a recording after the fact.
You want the tree of pros and cons (really, rebuttals / consequents /
syllogisms / a bunch of other smaller categories) because you’re trying to
capture the structure of the discussion itself.

 _Then_ , once you have captured that structure, argument-mapping software has
tooling to allow you to _massage_ (refactor!) the discussion from its original
shape, into one that lets you more efficiently get at the truth. Turn things
graphical, assign arguments weights, unify duplicate branches, etc.

Argument mapping is not _just_ about pro/con trees; but pro/con trees are a
nearly-lossless way to capture how people actually debate things, so they’re a
good “ingested primary source” format to keep around and refer back to when
you’re trying to summarize and judge a debate (rather than having to listen to
the audio transcript over and over, or read through a linear stream of debate
text.)

~~~
TeMPOraL
Huh, I haven't thought of using them as an _input_ format, a form that matches
the typical structure of a discussion. Thanks!

> _I think they expect you to draft the argument map, then go back over it and
> iteratively reduce it by manually normalizing duplicate sub-arguments into
> one canonical sub-argument in one place + references to it in other places._

That can work with this application/language. It doesn't work with Kialo,
unfortunately, where you had different people contributing different nodes of
the tree and AFAIR maybe, sometimes, someone then going over the tree and
cleaning it up.

> _Then, once you have captured that structure, (...) massage (refactor!) the
> discussion (...) into one that lets you more efficiently get at the truth._

One thing I tried to say is that I believe an argument tree isn't a right end
format here, both because it's about arguments (vs. facts and their
relationships), and because it's _a tree_. I think the end format must be a
directed graph, very likely containing cycles (mutually supporting arguments).

Why I don't like arguments in the final format? Because they're kind of like
an applied function. They hide the parameters. You can decompose an individual
argument into pieces of facts and their relationships; an argument takes
those, and assigns hidden weights to them - you care about some facts and
relationships more than others, and this is usually implicit in the argument
(and a source of confusion when doing this multiplayer, a-la Kialo).

I think it'll be more productive to decompose the arguments and deduplicate
the resulting graph, and then work at the facts-and-relationships level. The
benefits are that all components are now much easier to objectively verify,
and whatever conclusion you then read out of this graph could be validated
easier.

Note I just _think_ that it'll work better, I haven't really tried it. I have
on my TODO list somewhere to take a particular nontrivial topic, like e.g.
"animal suffering"[0], and try to decompose it this way to see whether this
format will actually work in practice.

\--

[0] - It's a topic on which I have no formed opinion at this point, only bunch
of inconsistent feelings and heuristics, so I shouldn't have too many
preconceptions and biases here. It also seems hard enough to teach me
something about myself.

~~~
SiempreViernes
>directed graph [...] containing cycles

Can you clarify what you mean with cycles? As written it sounds like you think
sound arguments contain circular reasoning...

I can see a branching opening and closing in a unidirected graph being the
result of a sound argument^, but since you cannot move freely in both
directions I don't know if it would count as a cycle.

^ The argument being: some process has a positive an negative effect (one
thing happens, another thing never happens), the positive and negative effects
are observed in nature, supporting the conclusion that the process in fact is
the cause of the two effects.

~~~
TeMPOraL
Feedback loops.

I don't think modelling "from argument X follows argument Y" is productive;
what's productive is modelling that observable phenomenon X is correlated with
Y, or causes Y, or has this-and-that impact on Y. At this level, things can be
stuck in feedback loops, either positive or negative.

Will increase in coal exports of Poland increase Poland's CO₂ footprint? Let's
try to model it the way I think about it:

    
    
         Coal exports
              ^
              | [provides Z coal to]
              |
              |     [needs α*X = A kWh for coal]
         Mining coal <---------------------\
              |                            |
              | [provides X coal to]       |
              v                            |
       Coal power plants                   |
        |     |                            |
        |     | [γ*X = Y kWh burning coal] |
        |     v                            |
        |  Electricity --------------------/
        |
        | [burned coal into β*X = N kg of CO₂]
        v
      CO₂ emissions
    

You have a cycle there: Mining coal -> Coal power plants -> Electricity ->
Mining coal. Given A < Y, it's a negative feedback loop. It's a cycle that
exists in real life (and the basis of the concept of EROI)!

If this were a reactive model, you could tweak the value of Z to see how X, Y,
A and ultimately N change. But even without reactivity, you can clearly see
that the answer to original question is "yes, increasing coal exports will
increase Poland's carbon footprint". And there's little left open to
interpretation or accusations of subjectivity.

If you don't like the answer that the model gives, it also makes some
alternative strategies apparent! In this case: can we find a way to reduce α
or β to compensate? Or increase γ? Or maybe add an alternative CO₂ sink for
the Coal power plants -> CO₂ emissions edge? Note that these alternative
strategies involve manipulating _reality_ , not your argument.

I think we should be doing more of this kind of modelling. Building more
accurate maps of the world, and reasoning straight from them, instead of
trying to build complicated webs of arguments.

------
breck
This source repo is really fantastic code. If you are implementing a new
language this is a nice one to emulate.

They've got a Language Server Protocol Implementation, VS Code Extension, Code
Mirror mode, and more, and the code and even config files project wide are all
very well done.

Great stuff.

~~~
broth
Would you be able to provide some specific examples?

~~~
broth
Not sure why on the downvotes. I was more curious if you could link to a
specific source file.

~~~
thegeekpirate
There's a GitHub link on the top-right of their home page.

~~~
broth
Right. I totally missed that. Thanks for pointing that out.

------
daenz
Very cool. Better technology in the area of discussion and disagreements will
go a long way (longer than I think most people realize). We need a "bicycle
for the mind" concept for online discussion.

~~~
toasterlovin
I agree. But this is half the solution. The other half is an authoritative
source that tracks the arguments and evidence for various hypotheses and
theories. So a layperson can understand the basic argument and the strength of
the evidence for or against it in about 15 minutes, but fractal in nature so
that one can descend all the way down to the raw data if they choose.
Something like Wikipedia, except for hypotheses and theories about how
existence works. Then we can just link people to a source that outlines the
flaws in their pet theories.

Side note: I think diet advocates and climate enthusiasts would be in for a
bit of a shock from such a resource when they have to deal with the fact that
epidemiology and model building are some of the weakest forms of evidence. But
I digress.

~~~
jmickey
This is something I have had at the back of my mind for a few years now - a
website that lets people upload hypotheses and link evidence that supports or
rejects the hypothesis.

Such a website would allow people to gain insights, by gathering individual
bits of evidence observed in various news articles, research papers, etc. and
linking them together to form a larger picture.

~~~
stevenhuang
No way, I've always wanted to create something like this too. This person
[https://news.ycombinator.com/item?id=20477924](https://news.ycombinator.com/item?id=20477924)
also shares our idea:

> I would love to see this baked into a social network as a substrate for
> semi-structured debate.

Gaining insight and collecting disparate facts to form a bigger picture, an
"argument map", with the ability for others to collaborate--that's exactly it.

However in addition to all the great use cases you've outlined, I also see
potential for personal use, particularly in making structured decisions.

For example, purchasing decisions: researching to buy or not to buy widget X
(in my case recently, sentiment analysis on stocks). With the creation of a
simple browser plugin that allows you to highlight text and quickly add it to
the map, it would make it easy to centralize all misc pieces of information
supporting/rejecting a decision. Supporting "evidence" added this way will
automatically link to the source, and optionally snapshot the page to ensure
context of the particular supporting evidence is never lost.

I think it would be a fun project to create. If you ever think to actually
work on this, or if you're interested in working on this together, let me
know!

~~~
nathan_f77
Me too! I would also love to build this, and I've actually been thinking about
it for ~5 years! This is one of the projects I was always planning to work on
if I didn't need to worry about money. I don't want to monetize the site with
ads, and I also didn't want to worry about chasing after donations. I was
thinking that the core product could possibly be monetized for businesses to
make better decisions, but that would be too risky (since most startups fail),
and it would also dilute the vision (Wikipedia-scale fact database with
weighted nodes and edges, to find answers and probabilities for humanity's
biggest questions.) I should have really started working on it a long time
ago.

I actually just started seriously thinking about it again over the last few
weeks, so this HN comment thread is really surprising! I'm definitely
interested in helping with development, and maybe sponsorship at some point in
the future.

EDIT: This HN thread was the kick I needed to get started, although I don't
know how much time I'll be able to spend on it. I'm really busy with my
startup, so this will have to be an evening/weekend project for now. I've just
registered FactGraph.org. (I'm not 100% sure about the name, but I haven't
been able to think of any better names.)

~~~
stevenhuang
Alright your recent edit has convinced me. I'm down to work on this together
if you are! I'll send you an email once my day's over.

Names like KnowledgeGraph etc were what I came up with previously. I'll check
my notes, think I had a few other good ones..

------
trumbitta2
I always look in wonder at how americans are so in argumentation. I mean, you
even have a whole set of tools and now a "markdown of sorts" for
argumentation.

As an european, this never ceases to amaze me.

~~~
smallnamespace
Americans are dualists [1] who believe there is both good and evil, and the
best thing is to have both (all) sides fight it out to see who wins.

You can see this throughout the culture, from the legal system, to robust
support for free speech, to the quite frankly Christian morality (a belief
that there is original sin in the body politic that must be atoned for) that
permeates even the most hardcore progressive, atheistic left.

[1]
[https://en.wikipedia.org/wiki/Dualistic_cosmology](https://en.wikipedia.org/wiki/Dualistic_cosmology)

~~~
swebs
You're half right. It's best to consider all sides of an argument, however the
people that believe that there are only two sides are generally considered
idiots. The fact that there are only two major political parties is just a
mathematical consequence of the election system, not a reflection of the
population's actual beliefs.

~~~
chongli
It's not just a mathematical artifact though. Political affiliation has deep
cultural significance in the US. It permeates every aspect of a person's life
and affects all of their relationships. There are plenty of Americans who will
demand to know what you think of the president, on first meeting you, and then
decide whether or not they like you based on the answer to that single
question.

You don't see this in countries with many political parties that each grab
only a small piece of the pie.

~~~
jhayward
> _There are plenty of Americans who will demand to know what you think of the
> president, on first meeting you, and then decide whether or not they like
> you based on the answer to that single question._

There are plenty of americans who will form their opinion of you based on
which sports team you like, as well.

I think your observation is not so much one of politics permeating all aspects
as it is that our current culture is superficially tribalistic in nature, with
many tribal signifiers being used.

------
goerz
The underlying project was “argunet”
([http://www.argunet.org/](http://www.argunet.org/))

------
chrvoigt
Hi, I'm the developer of Argdown. Thank you for all your feedback. As some of
you already mentioned, so far Argdown has been mainly used by philosophers in
an academic context, so it is great to hear what people with other backgrounds
think about it.

------
Waterluvian
Is there a syntax for pro/con weight? One issue I run into a lot is leaning on
a single massive point to counter a bunch of weak points.

------
garmaine
At first I thought this was a parser to automatically convert help text for a
command into an argument parser. Something I didn’t realize I needed until
right now. Someone write that thing too!

~~~
imurray
[http://docopt.org/](http://docopt.org/) — turns help text in a Python doc
string into an argument parser.

After a doc string put:

    
    
        import docopt
        args = docopt.docopt(__doc__, version='0.0.1')
    

Edit: krapht points out there is now support for multiple languages:
[https://github.com/docopt](https://github.com/docopt)

~~~
krapht
I use Docopt now for every CLI script I write, using Docopt language ports.
Skipping argument parsing boilerplate is so nice, not to mention now I don't
have to remember how each different language is supposed to idiomatically
parse CLI arguments.

------
krmbzds
This reminds me of arguman.org: [https://arguman.org/](https://arguman.org/)

------
dharmab
The map view relies on color for information, which makes it hard to read as a
colorblind user.

~~~
pas
And there's no legend/explanation for the colors at all on the pictures :(

And the black text color doesn't work that well on most of the backgrounds :/

------
hyperpallium
idea: reddit/HN tree-comments, with nodes liks in argdown. I.e. instead of a
"reply" button, you select the type of rebuttal. Sibling comments compete to
address that particular aspect the best.

You can instead open a deeper layer, to instead counter that point.

i.e. the kind of thing that can happen with tree-comments, just with explicit
structure.

------
natch
Needs some syntax for referring to definitions of terms used in the arguments.
Terms like “easier” and “complex” need formal, agreed on, definitions for the
example arguments to make any sense.

~~~
Asmod4n
Like this? [https://argdown.org/syntax/#statement-yaml-
data](https://argdown.org/syntax/#statement-yaml-data)

~~~
natch
That could work! They just need to show some examples of using it for that
purpose.

------
pithymaxim
In case it's useful I immediately got a dead link
[https://argdown.org/guide/a-first-
example/](https://argdown.org/guide/a-first-example/) from this page
[https://argdown.org/guide/](https://argdown.org/guide/)

~~~
dmix
Needs the .html, works on the left sidebar fortunately:
[https://argdown.org/guide/a-first-
example.html](https://argdown.org/guide/a-first-example.html)

------
vinceguidry
I would love to see this baked into a social network as a substrate for semi-
structured debate. Bookmarking for later reference.

~~~
bloopernova
I'd like to see something like this used to display people's arguments in
social media. Something like a mythical "machine learning argument analysis"
process would look at comments and threads, then spit out something like
Argdown. Then people could see what structure and flow different discussions
have.

Could also be useful if there was such a mythical tool that could gently teach
people to debate in a more logical manner. The user would write their comment,
but before it is submitted, it is analyzed and helpful tips or edits shown to
the user.

As an aside, I wonder how good grammar checkers have become since the Word 97
days? My grammar is utterly terrible and I wish I could get it proofread
before I make comments.

~~~
vinceguidry
That would be amazing. I'm putting that on my 'things to explore with machine
learning when I finally get into that space' list.

~~~
stevenhuang
Agreed, I'd very like to see something like this to be a thing.

------
sagebird
The default red/green background colors should be lightened dramatically, eg
ffcfcf and cfcfff. The colored arrows should just be black imo.

People will fuss over red green color blindness as well. May want to add a
small visual indicator that can be seen in a grayscale version, like a plus or
minus above each box, or the words pro and con.

This is a starting point, an experienced designer should be able to find
settings for a much better looking and functional default look.

~~~
chrvoigt
You are right, color blindness and grayscale exports are things we need to
think about. I added your ideas as an issue
([https://github.com/christianvoigt/argdown/issues/113](https://github.com/christianvoigt/argdown/issues/113)).

------
yetkin
Already a popular platform exist for some time
[https://en.arguman.org/](https://en.arguman.org/)

------
prvc
Using a tool such as graphviz directly allows for more flexibility. Reasoning
is not simply reducible to syllogisms and lists of pros and cons.

------
Tepix
I think this will also be useful for decision makers.

With this tool you can ask for pro and con arguments and have a good way to
write them down.

------
pmarreck
FYI to the owner of Argdown.org if around- Your getting started page linked
here 404's: [https://argdown.org/guide/a-first-
example](https://argdown.org/guide/a-first-example)

~~~
chrvoigt
Thanks! I added an issue for this
([https://github.com/christianvoigt/argdown/issues/115](https://github.com/christianvoigt/argdown/issues/115))
and will fix this as soon as I find the time.

------
rolling_robot
It would be really nice to have emacs package that supports argdown
compilation and syntax.

~~~
imiric
If you're already using Emacs, this use case seems like it could be handled
with org-mode and a custom export implementation.

~~~
rolling_robot
Nice, I think that would be even better.

------
carlsborg
Amazing work, this is phenomenal. It says it is funded by Debatelab
[http://debatelab.philosophie.kit.edu/](http://debatelab.philosophie.kit.edu/)
which is also fascinating.

------
lallysingh
Orthogonally, I wish there was a better mechanism to embed various markups in
code comments. Something that editors can render in-place.

Arguments like this would be perfect for in-situ descriptions of design
decisions.

------
p0nce
I think I will use it for myself, because opinions are "lazy" for me (I
produce one when I need one) but I don't think they are self-consistent,
except for the expert philosophers.

------
carapace
See also "Laws of Form" notation, diagrams as logical formulas.
[http://www.markability.net/](http://www.markability.net/)

------
avivo
This link was much more helpful:
[https://argdown.org/sandbox/map](https://argdown.org/sandbox/map)

------
astro-codes
The argdown theme in vscode (that is recommended to install) is surprisingly
nice as well. Does anyone know if it's a derivative of something?

~~~
astro-codes
Just realised that it is the default vscode light theme! I clearly have never
used it ...

------
majkinetor
Can never get enough of documentation as source code (DaSC) tools :)

This looks awesome. This would be way more cumbersome in plantuml.

Big thanks to authors.

------
crooked-v
So... what _is_ it, exactly? That page has a lot of words, but they're not
ones that make any sense to me.

~~~
paulfurley
Agreed:

“argumentation”, “pro & contra lists”, “dialectical relations” “premise-
conclusion structures

..all appear within the first 100 words and I don’t know what any of them
mean. I’m a a native English speaker with a technical education and I am lost!

Is the site aimed at some profession where these words are commonly used?!

~~~
confused-k
Before I gave up on finding out what this was and closed the website, I saw
that the copyright author on the bottom of the page was German or affiliated
with a German university. I'm fine with giving the person a pass on some of
this language, and drawing on the German I know (and having lived there,
somewhat familiar with how Germans would say things in English), I think:

\- _argumentation_ should be _arguments_ or in more words: "these are the
arguments I'm presenting to support my claims."

\- pro/contra is pros/cons

\- I have never heard the word 'dialectical'

\- premise-conclusion structure I think is something like hypothesis-
conclusion, maybe?

~~~
weavie
Dialectical comes from greek philosophy where the proponents of two opposing
views would have a conversational debate with reasoned arguments to try to
find the truth.

[https://en.wikipedia.org/wiki/Dialectic](https://en.wikipedia.org/wiki/Dialectic)

------
tingletech
looks like it might make a good general purpose graph editor

~~~
stefco_
The dot language used by graphviz is simple enough and portable to web
implementations [0][1]. I think this is more useful for its specific domain.

[0]
[https://github.com/dagrejs/dagre-d3/wiki](https://github.com/dagrejs/dagre-d3/wiki)

[1] [https://github.com/mdaines/viz.js](https://github.com/mdaines/viz.js)

~~~
tartrate
TBH I think the Argdown source is much more readable than this I found from
one of your links:

    
    
        /* Example */
        digraph {
            /* Note: HTML labels do not work in IE, which     lacks support for <foreignObject> tags. */
            node [rx=5 ry=5 labelStyle="font: 300 14px     'Helvetica Neue', Helvetica"]
            edge [labelStyle="font: 300 14px 'Helvetica Neue',     Helvetica"]
            A [labelType="html"
               label="A <span style='font-    size:32px'>Big</span> <span style='color:red;'>HTML</span>     Source!"];
            C;
            E [label="Bold Red Sink" style="fill: #f77; font-    weight: bold"];
            A -> B -> C;
            B -> D [label="A blue label" labelStyle="fill:     #55f; font-weight: bold;"];
            D -> E [label="A thick red edge" style="stroke:     #f77; stroke-width: 2px;" arrowheadStyle="fill: #f77"];
            C -> E;
            A -> D [labelType="html" label="A multi-rank <span     style='color:blue;'>HTML</span> edge!"];
        }

~~~
stefco_
Like I said, I agree for _verbose_ cases like complex logical arguments, where
the contents of each node are longer and should look more paragraph-like.
You're also picking an example with tons of formatting in it. If you have a
bit less formatting, shorter node labels, and proper indentation, it looks
great. From the second library I linked's demo page [0]:

    
    
      digraph G {
      
       subgraph cluster_0 {
        style=filled;
        color=lightgrey;
        node [style=filled,color=white];
        a0 -> a1 -> a2 -> a3;
        label = "process #1";
       }
      
       subgraph cluster_1 {
        node [style=filled];
        b0 -> b1 -> b2 -> b3;
        label = "process #2";
        color=blue
       }
       start -> a0;
       start -> b0;
       a1 -> b3;
       b2 -> a3;
       a3 -> a0;
       a3 -> end;
       b3 -> end;
      
       start [shape=Mdiamond];
       end [shape=Msquare];
      }
    

Or, if you don't care about colors and shapes (which you probably don't on a
first pass-through):

    
    
      digraph G {
      
       subgraph cluster_0 {
        a0 -> a1 -> a2 -> a3;
        label = "process #1";
       }
      
       subgraph cluster_1 {
        b0 -> b1 -> b2 -> b3;
        label = "process #2";
       }
       start -> a0;
       start -> b0;
       a1 -> b3;
       b2 -> a3;
       a3 -> a0;
       a3 -> end;
       b3 -> end;
      }
    

It's not the prettiest once you start using the advanced formatting features
(some of which are already present in the first example), but it's simple and
straightforward enough for manual or scripted graph layout/rendering across a
broad range of use cases, and I highly recommend it as a go-to. I use it to
autogenerate DAG plots in my multi-messenger astrophysics library
documentation [1] and also manually to reason through things, though, again, I
agree that Argdown's syntax looks better for the latter verbose use case.

I was just disagreeing with the notion that Argdown is useful in the _general_
case, where I find that graphviz .dot format is already closer to what I would
want a general graph-layout markup language to look like (despite being far-
from-perfect). It's less optimized for the verbose case, but it starts pretty
minimal and can be extended without too much pain in whatever direction is
best.

[0] [http://viz-js.com](http://viz-js.com)

[1]
[https://multimessenger.science/llama.pipeline.html](https://multimessenger.science/llama.pipeline.html)

------
spookyuser
This looks amazing! Can't wait to try it out.

------
DiabloD3
Who's the target market for this?

~~~
goerz
Philosophers. We were using the early predecessor of this in our philosophy of
science course 10 years ago or so (the TA was the guy who’s now the professor
behind this project). It’s a pretty neat way to analyze informal logic.

------
spookyuser
This looks amazing, can't wait to try it!

------
lloydatkinson
The documentation is written with a Vue.js static site generator documentation
tool called VuePress. You use markdown for that, ironic.

------
dlphn___xyz
this would be helpful in jupyter notebooks i hate having to draw decision
trees with graphviz

------
injidup
And there I was thinking that it was a CLI argument parser generator.

~~~
0xfi
glad I wasn't the only one

