tsort: add page

[MasterOdin]

A command from the list in #2213

• The page (if new), does not already exist in the repo.

• The page (if new), has been added to the correct platform folder:
  common/ if it's common to all platforms, linux/ if it's Linux-specific, and so on.

• The page has 8 or fewer examples.

• The PR is appropriately titled:
  <command name>: add page for new pages, or <command name>: <description of changes> for pages being edited.

• The page follows the contributing guidelines.

[tldr-bot]

The build for this PR has failed with the following error(s):

pages/common/tsort.md:5: TLDR104 Example descriptions should prefer infinitive tense (e.g. write) over present (e.g. writes) or gerund (e.g. writing)

Please fix the error(s) and push again.

[sbrl]

Erm I'm confused! What does this do? That's a lot of words jumbled up in that sentence.

Perhaps we could add some additional clarity in a second line of the command description too - maybe something like this?:

> In other words ......

[MasterOdin]

Yeah, that was my worry when I wrote this.

Essentially, it takes a file where each line is some list of "dependencies":

a b c
d
e f
b c d e

which can be read as:

• a is before b which is before c
• e is before f
• b is before c which is before d which is before e

and produces a topological sort of it:

a
b
c
d
e
f

So the gist of that sentence is:

• Produces a topological sort of a file which has some number of lines
• Each line of the file gives a partial ordering of elements for the sort
• Each element is separated by a space

I'm not sure how wordy of an explanation you guys allow to expand on that singular sentence.

[sbrl]

Ah, I see. What kind of use-cases are there for this kind of thing? Perhaps we could use one to relate the idea better.

[MasterOdin]

The use case would be to see the ordering of dependencies within a directed acyclic graph (a common example is function calls within a program).

[agnivade]

We can condense it to - Perform a topological sort consistent with a partial sort per line of input separated by blanks:

[sbrl]

Ah, ok! Perhaps we could add a 2nd description line saying A common use is on function calls in a program.?

[sbrl]

Thanks, @MasterOdin 😺