Section: N/A ReadChanges --- title: Idealogs:Documentation --- is documentation for the [@0xAA17A6] project. ## Articles A [@0xB57941 | synesiary] (e.g. Idealogs) is a wiki that catalogs subjects of interest, along with their relevant writings, statements, and questions (WSQs). This corresponds to four different types of articles in the wiki, each represented by its own unique [domain](#handles): | Item | Article Type | Domain | Content | ---- | --- | ------- | -------- | subjects of interest | [@0x8A0BB9#definite \| Definite] | \@0 | A literature review of the most important WSQs that shape our understanding of the subject. | writings | [@0x8A0BB9#transfinite \| Transfinite] | \@T | A summary/analysis of the writing, using the special linking mechanism to make references to and inferences from the text. | statements | [@0x8A0BB9#infinite \| Infinite] | \@I | An explanation of the statement and a summary/analysis of the proofs that substantiate it. All proofs must be sourced from primary sources already cataloged on the site as writings. | questions | [@0x8A0BB9#finite \| Finite] | \@F | A summary/analysis of the question. This article should layout all the relevant sides of the debate, explain where the sides agree and disagree, describe the question's origin and evolution over time, and spell out any other information that helps put the question in context. In other words, this article should spell out the question's Five Ws: "Who, What, When, Where, and, Why". Our underlying mindset is to seek to define the question, not answer it[^caveat]. [^caveat]: With that said, the answer will frequently reveal itself naturally as the article matures over time (in theory). See [@0x8A0BB9] for a deeper discussion of the four types of articles and what goes in them. ### Handles Unlike in a traditional wiki, articles on this site are identified by a unique [@0x91CEEB#why-handles | handle]. Handles are composed of a domain and a range, and are formatted as [domain]x[range]. Ranges are encoded in hexadecimal (see [ranges]). This article has the handle **\@0x66F7B7**, which means it is in the '\@0' domain and thus refers to a subject. Some more examples: | Handle | Domain | Range | Translation | ---- | --- | --- | ------- | \@0x0 | \@0 | 0 | a subject article | \@TxA | \@T | A | a writing article | \@IxEF3 | \@I | EF3 | a statement article | \@FxB22A8 | \@F | B22A8 | a question article | \@Enderx3 | \@Ender | 3 | an article published by the user \@Ender outside of the wiki. See [works] for more info. ### Domains Domains are a tool to quickly identify which type of article you are reading. There are four default domains, corresponding to the four types of [articles] in a synesiary. When you create an account, you are also assigned your own domain which corresponds to the Pen Name you chose. See [works] for more info. ### Ranges Ranges are automatically generated by the software when you create a new article. They are relevant only in that they allow you to uniquely refer to any article in a given domain. Ranges use the hexadecimal numeral system. ### Titles The [title](#synesiary-yaml-specification) of an article is located at the top of the page. It identifies the item being cataloged in the fewest words possible. The title of an article can be changed freely from edit to edit. This is because an article is uniquely identified by its handle, not its title[^moving]. In practice, title edits must be properly justified or else they will be reverted. [^moving]: this is in direct contrast to Wikipedia, where articles must be "moved" in order to change their title ### Subtitles The subtitle of an article, located directly beneath the title when visible, displays the article's handle. If you are on the article's "Read" page, the shortcut CMD+S will show or hide the subtitle. ### Meta You can easily view pertinent information about the commit you are viewing by clicking the handle of the article, located in the subtitle. For example, scroll to the top of this page and click the link for '\@0x66F7B7'. The log will also provide a button for editing the article (if you have permission to do so), and also a button for viewing the changes made by this commit, among others. If you are on the article's "Meta" page, the shortcut CMD+M will show or hide the meta box. ### URLs The URL of an article is simply the article's handle. ### Commits An article in a synesiary is the sum of a finite number of commits. A commit is roughly equivalent to an 'edit' in a wiki. ### Suffixes The four article types in a synesiary each have an associated suffix that is used for [searching](#searching) for and [creating new articles](#creating-new-articles) of that type. | Article Type | Catalogs a | Suffix | --- | --- | --- | [@0x8A0BB9#definite \| Definite] | subject | `;` | [@0x8A0BB9#transfinite \| Transfinite] | writing | `,` | [@0x8A0BB9#infinite \| Infinite] | statement | `.` | [@0x8A0BB9#finite \| Finite] | question | `?` For example, to query the index for all finite articles (i.e. questions) concerning World War 2, you would input `World War 2?`. If your query does not end in an appropriate suffix, then you will receive results from all four domains. ## Pages Every synesiary article is composed of two pages: an Article page, and a Talk page. This is identical in structure to a standard wiki, and the properties and functions of each are parallel to their wiki counterpart. Transfinite articles have an additional page, called a [Text page](#text-pages). This is something unique to a synesiary and not found in other wikis. ### Article page Identical in function to the Article[^ken] page of a Wikipedia article. [^ken]: Also known as a "Ken" page. Ken (n.) means understanding, as in *beyond one's ken*. A Ken page is place for understanding. ### Talk page Identical in function to the Talk page of a Wikipedia article. Common syntax for editing a Talk page: | Syntax | Explanation | --- | --- | `[@user]` | Sends `@user` a notification that they've been mentioned in the edit. | `~~~~` | Inserts a user's signature into the edit. Used to attribute a comment to its author. | `>` | Text indent. Used to format edits in the form of a conversation. ### Text page All transfinite articles are associated with a writing which the article is meant to [@0x8A0BB9#transfinite \| catalog and describe]. If the writing was published as a [work](#works) or was published elsewhere on the web, then the "Text page" is simply a link to the writing itself; if, however, the writing is in the public domain or we have secured the rights to republish it, then it is a bona fide wiki page itself which can be edited like any other page in the synesiary. In other words, there are three categories of writings based on where the writing was originally published: | Category | Description | Text page | --- | --- | --- | Published elsewhere | The most common case. The transfinite article creates a reference to the original publication. | A link to the writing if one exists. | Published on this site | A [work](#works). See [below](#works) for more info. | A link to the writing. | Published elsewhere, but republished here | Either a writing in the public domain, or one which we secured the rights to republish. This type of transfinite article has a Text page which houses the republished writing, and which can be edited like any other article in the wiki. For an example, see [@Tx12F990]. | An actual wiki page which can be edited like any other. ## Creating New Articles <figure class="fullwidth"> | If I'm cataloging… | Then I enter... | Example | Identifier | Suffix | -------- | ----- | ------ | ---- | ------ | a subject | identifier**;** | Cheese**;** | title | ; | a writing | identifier**,** | https://www.example.com/mmmmm-cheese**,** | URL/DOI/PMID/ISBN if possible; title otherwise | , | a statement | identifier**.** | Cheese is delicious**.** | title | . | a question | identifier**?** | Why is cheese so delicious**?** | title | ? </figure> In the top left corner of the Idealogs home page, there is a link that says 'new'. This takes you to the tool for creating new articles in the wiki. Alternatively, go to the sidebar and click the "New article" link in the "Contribute" section. To create a new article: 1. Enter the article's **identifier** followed by its **suffix** to specify which domain the article belongs in. Hit 'Enter'. 2. Check the results below to ensure the article does not already exist on the site. 3. Press 'Submit'. The article's identifier and suffix depend on whether you are cataloging a subject, writing, statement, or question: For example, the query `What is the answer to life, the universe and everything?` will generate the option to catalog 'What is the answer to life, the universe and everything?' as a question in the wiki. ### Writings If you are cataloging a piece of writing that has a unique identifier, use it in your query. Doing so will allow the software to automatically add relevant bibliographic metadata to the article. Examples of unique identifiers include * URL (ideally, a stable one) * DOI * arXiv ID * PMID * ISBN <figure class="fullwidth"> | Identifier Type | Writing | Query | --- | --- | --- | DOI | The academic paper "The spread of true and false news online" (2018) | `10.1126/science.aap9559,` | URL | The article from the Washington Post that first reported the Saturday Night Massacre | `https://www.washingtonpost.com/politics/nixon-forces-firing-of-cox-richardson-ruckelshaus-quit-president-abolishes-prosecutors-office-fbi-seals-records/2012/06/04/gJQAFSR7IV_story.html,` </figure> Notice the comma at the end, which is the suffix for cataloging writings and not part of the identifier. ## Editing To reach an article's editing interface, either click the 'Edit' link in the top right of the page, or click the 'Edit' button that is accessible via the article's [meta](#meta) block. ### Authenticated vs. Anonymous The editing workflow of an article differs depending on whether you are signed in or not. The latter is nearly identical to the editing workflow on Wikipedia: make your changes, write a short message which describes your changes, preview the changes you are about to make, and then commit them to the database. The former provides more flexibility. You can * save uncommitted changes as you work; * click the 'Changes' button to highlight the changes you have made so far; and * quickly access all the articles you are actively working on from your 'Workspace', located in the upper right corner of the screen. ### Markdown Articles on this site are written in Markdown. If you are unfamiliar with Markdown, do not be afraid! It is easy to learn. I recommend googling 'Markdown Tutorial' and checking out the first few links. Another easy way to learn it is to simply click 'Edit' on some articles on this site to see how it works. This site uses Pandoc-flavored Markdown. ## YAML Headers Idealogs uses YAML header blocks for storing article metadata. A great way to learn more about YAML headers and how they work is to find transfinite articles on the site and look at their source. ### Citation Style Language The vast majority of the fields in a synesiary article YAML header are as specified by the Citation Style Language (CSL) format. See their spec [@TxF3B1EE] for more details. ### Synesiary YAML Specification There are, however, a couple custom and/or modified fields which are specified below. | Field | Example | Required | Usage | Notes | ----- | --- | --- | --- | --- | `title` | `title: Hello World!` | yes | All articles | All articles must have a title | `comments_on` | `comments_on: Tx3` | no | transfinite, [works] | The article being commented on must be transfinite. Once this field is set, you can make [direct links](#direct-linking) to the writing you specified. | `PDF` | `PDF: https://tyfried.github.io/files/discourse.pdf` | no | transfinite | For use when the primary source is a PDF hosted somewhere on the web. Also used specifically in conjunction with [direct linking](#direct-linking). ### References In addition to the above, transfinite articles use the YAML header block to store bibliographic data about the writing in the Citation Style Language (CSL) format [@TxF3B1EE]. This metadata is then used to generate a reference for the writing using CiteProc [@TxF4D95F]. To display a reference at the bottom of a writing article, ensure that the final line of the document is ```markdown ... ## Reference ``` The software will then autogenerate a reference using the metadata provided. Note: this line is added to the end of writing articles by default. ## Linking Linking to other articles in the synesiary is very easy. All you need is the article's handle. | Markdown Syntax | HTML | Notes | ---- | ---- | --- | `[@TxA]` | `[<a href="/@TxA">TxA</a>]` | NA | `[@TxA; @Ix6]` | `[<a href="/@TxA">TxA</a>, <a href="/@Ix6">Ix6</a>]` | NA | `[@0xAA17A6]` | `[<a href="/@0xAA17A6">Idealogs</a>]` | Only works for definite articles | `[@0xAA17A6 | Hello World]` | `[<a href="/@0xAA17A6">Hello World</a>]` | Only works for definite articles Note that when you link to an article, the text of the link is simply the handle itself. This is not true for linking to definite articles, however. By default, the text of the link will be the title of the article, but you can change what text is displayed as in the example above. This only works for linking to a single definite article, though. In particular, something like `[@0xZ | something else; @IxZ; @FxZ]` would be invalid. Also note that traditional markdown linking is [@0x91CEEB#why-i-cant-i-create-links-to-websites-and-images-the-normal-way | forbidden] in a synesiary. ### Direct linking Within [@0x8A0BB9#transfinite \| transfinite] articles and [works], there is a special syntax for making links directly to text fragments [@Tx1D6121] or other specific locations within the primary source that is being cataloged. | Markdown Syntax | Example | HTML | Works for | ---- | ---- | --- | --- | `[textDisplay | textSource]` | `[Brown fox | the quick brown fox]` | `<a href="https://www.example.com#:~:text=The%20quick%20brown%20fox">Brown fox</a>` | HTML | `[textDisplay | textSourceStart | textSourceEnd]` | `[Brown fox | The quick brown | lazy fox.]` | `<a href="https://www.example.com#:~:text=The%20quick%20brown,lazy%20fox." >Brown fox</a>` | HTML | `[textDisplay | #page=XXX]` | `[Page 70 | #page=70]` | `<a href="https://www.example.com/test.pdf#page=81" rel="noopener">Page 70</a>` | PDF | `[textDisplay | #whatever-you-want-here]` | `[Hello world | #hello-world]` | `<a href="https://www.example.com/test.pdf#hello-world">Hello world</a>` | HTML Note: this text fragment highlighting feature is only supported by Chromium based browsers (e.g. Chrome, Edge) at the moment. ### Reciprocal Linking A synesiary uses the [KenScore](#kenscore) metric to rank each article based on how many [@0x2A91BA | reciprocated] internal links it contains. In short, the more reciprocal links an article has, the higher its visibility is in [searches](#searching), and vice versa. ## Front page The front page of Idealogs is a feed of articles ranked according to the [KenScore](#kenscore) metric. The feed is [searchable](#searching). ## KenScore Every article in the synesiary is ranked according to a custom metric called KenScore. It was inspired by and operates similar to Reddit's original hot ranking algorithm [@TxA484FF]. ### Basics Every time an article links to another in the synesiary, one of the articles receives a score for that link, according to the following logic: the article with a lower number of [symmetrical links](#reciprocal-linking) receives a negative "link initiation" score at the time when the asymmetrical link is first created, while the article with a greater number receives a positive "link reciprocation" score at the time when the asymmetrical link is reciprocated and becomes symmetrical. If the articles have the same number of symmetrical links, then the more recently created article is considered to be article with less symmetrical links. An article's KenScore is the median value of all its link initiation and link reciprocation scores. In theory, this - creates a live, up-to-date feed of the best writings, statements, and questions being discussed in the world right now, ie a veritable slice of what is "currently going on"; - increases exposure to ideas which are already well-established according to the number of reciprocated links they contain; - decreases exposure to newer ideas that have not yet gained traction; - and incentivizes authors who publish [works](#works) or writing elsewhere on the web to be creative and include new, original thought in their work if they want to have it receive exposure in the synesiary as a [@0x8A0BB9#usage | transfinite] article. This is a direct result of the emphasis on [@0x2A91BA | reciprocal linking]: asymmetrical links are associated with [@0x2A91BA#solution | repetitive and/or derivative thinking], and when not reciprocated they either decrease or have no effect on the exposure of the articles involved. ### Setup: givens, definitions Let $|X_t|_{sym}$ and $|X_t|_{asym}$ be the number of symmetrical and asymmetrical links in article $X$, respectively, at time $t$. Let $\mathbb{L}_{X_t}$ be the set of articles which link to $X$ or are linked to by $X$. Let articles $A$ and $B$ be two articles in the synesiary such that $|A_t |_{sym} \leq |B_t |_{sym}$. Let time $U$ be the moment that an asymmetrical link $L_{AB}$ was **initiated** between articles $A$ and $B$, and time $V$ be the moment that the asymmetrical link $L_{AB}$ was **reciprocated** by the other article, $U < V$. It is irrelevant which article initiated the link and which reciprocated; article $A$--the one with fewer symmetrical links--will always receive the lower score and article $B$ will always receive the higher score. Let time $W$ be September 9th, 2003 1:21:17 p.m. ET Let $s_{asym}$ be the difference in seconds $$s_{asym} = U - W,$$ and $s_{sym}$ be the difference in seconds $$s_{sym} = V - W.$$ Let $x(t)$ be the average of the difference in asymmetrical and symmetrical link counts in $A$ and $B$ at time $t$ $$x(t) = \text{avg}(|A_t|_{sym} - |A_t|_{asym}, |B_t|_{sym} - |B_t|_{asym})$$ and $y(t)$ be the maximal value of $x(t)$ and 1 $$y(t) = \max(x(t),1).$$ ### Setup: Link Initiation Score At time $U$, $L_{AB}$ is initiated and article $A$ receives the link initiation score $LS_{init}$ $$LS_{init}(L_{AB}) = log_4 y(U) - \dfrac{s_{asym}}{27000}.$$ ### Setup: Link Reciprocation Score At time $V$, $L_{AB}$ is reciprocated and article $B$ receives the link reciprocation score $LS_{recip}$ $$LS_{recip}(L_{AB}) = log_4 y(V) + \dfrac{s_{sym}}{27000}.$$ ### KenScore The KenScore for article $A$ at time $t$ is calculated as the median value of all of $A$'s link initiation and link reciprocation scores $$KS(A_t) = \text{med}( LS_{init}(A_t) \cup LS_{recip}(A_t))$$ where $$LS_{init}(A_t) = \{ LS_{init}(L_{AX}) \ \text{for} \ X \in \mathbb{L}_{A_t} \}$$ and $$LS_{recip}(A_t) = \{ LS_{init}(L_{XA}) \ \text{for} \ X \in \mathbb{L}_{A_t} \}.$$ ### Result The result of the KenScore metric is a time-based feed of all the articles in the synesiary based on how often and recently each individual article has been linked to and the relative quality of all of its links. It is very similar to and inspired by Reddit's original front page algorithm. ## PageRank Every article is also ranked according to the out-of-the-box PageRank algorithm. Every article is a node, and every inter-article link is a uni-directional edge in the graph. The PageRank metric is used to provide more accurate search results. ## Searching There are two ways to search for articles in Idealogs which provide two very different user experiences, depending on whether you include a [suffix](#suffixes) in your query or not. The default search method uses the [KenScore](#kenscore) metric. When you first land on the Idealogs home page, you will see all articles ranked according to this algorithm. Further, if you search for an article using the keyword search and *do not include* one of the four [suffixes](#suffixes) in your search, then the search result will simply filter out articles from this ranked list that don't match the keywords you provided in your query. The secondary search method uses the [PageRank](#pagerank) metric. If you *do include* a suffix in your query, then the search result will return articles ranked by relevance according to the keywords you provided and the article's overall PageRank. In other words: | If your query... | then your search result will use the ... metric. | --- | --- | does not include a [suffix](#suffixes), | KenScore | includes a [suffix](#suffixes), | PageRank ## Shortcuts There are a number of shortcuts on Idealogs to quickly accomplish commonly performed tasks. Javascript must be enabled for these shortcuts to function properly. ### Read Page <figure class="fullwidth"> | Shortcut | Action | Notes | --- | --- | --- | `CMD + M` | Show/hide article meta | `CMD + S` | Show/hide article subtitle | `CMD + D` | Toggle between the article and the underlying [writing](#text-page) | Only applies to transfinite articles associated with a writing published on this site </figure> ### Edit Page | Shortcut | Action | Notes | --- | --- | --- | `CMD + S` | Save your current progress | `CMD + E` | Show/hide a current preview of your edit | `CMD + D` | Switch text direction from left-to-right (LTR) to right-to-left (RTL). Useful for editing text in a RTL language (e.g. Hebrew, Arabic) | `CMD + M` | Moves the cursor to the "Message" input box | Only if editing anonymously | `s` | Moves the cursor to the search box ### Changes/Stage Page | Shortcut | Action | Notes | --- | --- | --- | `CMD + SPACEBAR` | Jump to the next change | `CMD + B` | Jump to the previous change | `CMD + M` | Moves the cursor to the "Message" input box | Only for `Stage` ### List view "List view" refers to any page on the site that is a list of objects. | Shortcut | Action | Notes | --- | --- | --- | `CMD + E` | clear the contents of the search box ## Accounts You can create an account on Idealogs, but doing so is not necessary. The benefits of an account are that you can save drafts, publish your own [works] separate from the wiki, and contribute to the works of other users. ### Home Page Your account home page is accessible from the top right corner of the screen. Your home page shows a log of all your commits on the site, sorted by time. ### Panel Your account settings are located in your panel. The panel is accessible from your user home page when you are logged in. From your panel you can access your workspace, set your bio, turn hints on/off, see the articles you are watching, see the domains that you contribute to, etc. ## Works A **work** on Idealogs is a version controlled document that can be published on the site but outside of the wiki. Once a work is published, it can no longer be edited. If merited, however, the community can catalog the work as a [transfinite article](#articles) in the synesiary so it can be integrated into the larger conversation and cited appropriatedly. A work has features similar to a *project* in a version control hosting service[^github] and a *post* in a blog. [^github]: e.g. GitHub, BitBucket ### Workspace Starting from the 'Workspace' tab in the top right, press 'new'. This will allow you to create an empty work. ### Domains By default, works are published under your default domain, the one that is associated with the account you created. You can also create new domains to publish under. All user-created domains must begin with "The ". Domain creation is accessible from the 'Domains' tab in the top right corner of the screen. It is not possible to change the domain of a work once it has been created. ### Handles Like articles in the wiki, all works have a handle that uniquely identifies it. A handle is composed in the same way: [domain]x[range], where 'domain' is the domain that the work is being published under. ### Home Page The work home page is the document itself, and is located at /\@[domain]x[range]. ### Visibility When creating a draft, you can choose its visibility. | Visibility | Description | ---- | --------- | Private | The work is hidden from the site until you publish it. Only you and people you explicitly choose can access the work until it is published. | Public | The work is visible to all users. Any user can make a pull request for their changes to be committed to the work. Only you and contributors you explicitly choose can approve pull requests. Only you and contributors you explicitly choose can commit directly to the work. | Open | The work is visible to all users. Any user can commit their changes without your approval. The difference between an open work and an article in the synesiary is that once the former is published, it can no longer be edited. ### Contributors You can add contributors to your domains to allow for collaboration among multiple users. This is most applicable when you have a private work that you want to give another user access to. To add a new contributor to your domain: from the domain home page, click the 'contributors' link, and then 'new'. ### Contributor Roles As the owner of a work, you can assign roles to users who are contributors to that domain. This feature is accessible from the 'Settings' link on the work's home page. | Role | Applies To | Description | --- | ---------- | ---------- | Editor | private, public, open | Can edit the work. Can add/remove contributors. Can accept or deny pull requests for public works. Can publish a work (if there are two or more editors, publishing requires the approval of all of them.) Default role for user that created the work. Note: once an editor is added to a work, they cannot be removed. | Approver | private | Can approve a work for publication. Can edit the work. This role can only be assigned by the owner of the domain. This role only applies to private works published under non-default domains (domains that begins with 'The'). | Writer | private, public | For private works, can read and commit. For public work, can commit. | Reader | private | Can read, but cannot commit. | Requester | public | This is role auto-assigned by the software to any user that makes a pull request to the work and doesn't have a pre-defined role. | None | public, open | Use in the case where you need to block someone from contributing (e.g. in the case of vandalism) ## Version Control System Idealogs implements a simplified version control system for editing documents. The same system applies for works in your workspace and articles in the synesiary. This is necessary in order to support features like drafts, documents with multiple contributors, and pull requests. Every edit exists in one of the following states. | State | Description | --- | ------ | Saved | A draft. Only visible to the user who created it. | Staged | A draft that is about to be committed. Only visible to the user who created it. | Head | The most recent commit. | Committed | Any commit that was made prior to Head. | Requested | A pull request. | Approved | A Head commit of a work that has been approved for publication by an approver. | Published | The Head commit of a work that has been published. | Submitted | The Head commit of a work that has been published and then submitted for cataloging in the synesiary. | Rejected | A pull request that has been rejected by the work's editor. You can continue editing it as a draft by patching its changes into the current head commit of the article. | Readonly | A saved edit of a work that has been published and thus can no longer be edited. These changes can only be discarded. ReadChanges
