@t[Nindish]~~META:date created = 2021.06.29., 17:17~~

This is the description of the planned Nindish language, a tool to process literary works in the aim of helping the author’s work.

@s6[Basic Principles]

A book is defined as one or more Unicode plaintext files. They are uploaded to a web server and presented to the Nindish app. Everything what the app should know about the book is contained in the files.
Each time the app is called, it downloads the files, runs the complete process, returns the data requested and quits. No data is saved for later, therefore, if the text is anyhow changed before the next reload, the change will be shown in the results.
All configuration settings about the book are contained in the book itself (but that part may be a separate file).

@s6[Features]

The results given by the functions listed below may or may not become part of the finished book, as you like it. They are intended to be writing aids, to make yourself able to navigate in your book easier, to find things in the text that were written earlier and become important later, to keep track of what you write and so on.
In the following, “mark pieces of text” means enclosing it between certain symbols (you define which ones). All background material about your book is self-contained in the text of the book.
**;;y:Titles and Table of Contents.;;** You can mark pieces of text as titles, including their ranks in a hierarchy of chapters, subchapters and so on. You can get a table of contents from these titles.
**;;y:Tag Index.;;** You can mark pieces of text as tags, complete with descriptions. The tags can be grouped into categories. You can get an index of these tags, by a category or those that begin with a given letter etc. For each tag, you’ll get the description you gave.
**;;y:Notes.;;** You can add notes to your text that help you in writing but won’t be an actual part of the finished book.
**;;y:Special Collections.;;** You can mark pieces of text as members of special collections such as quotations, and get lists of them.
**;;y:Statistics.;;** You can get extensive statistics about your book and parts of it, including sizes, time elapsed since beginning the book and so on. (Logically, this data won’t be part of the finished book.)
**;;y:Markup.;;** You can use any markup language like HTML, Wiki, BBCode etc., including your own markup language. Nindish doesn’t understand any of them, but you can define your special markup and create correspondences between the markup you are using and the output rendered by Nindish.
**;;y:Macros.;;** You can define macros that can appear in your book and simplify complex text manipulation tasks.
**;;y:Rendering.;;** You can render your book or a part of it into the near-final text where your markup symbols are replaced by actual formatting. I said “near-final” since Nindish cannot create a complete, readable Word, PDF etc. file, only the raw material for later processing.
**;;y:Images.;;** You can attach images to your book. They will appear in the renderings.
**;;y:Counters.;;** You can define counters that maintain some statistics about your book, in addition to those Nindish provides by default.
**;;y:Timelines.;;** You can define several timelines for the events in your book (several because it’s possible that different parts happen at different times).

@s6[Writing a Book With Nindish]

Nindish is a web app, so it has a URL you enter in your browser. Its parameters include the location of your book (exactly, the file containing its init part) and any switches telling which part of the information provided by Nindish do you need. You can reach these by clicking links on the pages created by Nindish or by calling them directly from your browser.
Nindish hasn’t got a text editor. Use your favorite one and upload your files to any server. Provide the names of your files in the init part, and call Nindish with the URL of the file with the init part.

@s5[The Init Part]

The first file of your book begins with the init part. (Or it may be a separate file.) This tells Nindish everything it needs to know about your book.
The init part tells Nindish which files contain your book, what are the symbols used in it, and so on.
The init part has a fixed syntax, modelled after the common INI file syntax. It consists of //sections// which are a name between ''[ ]'' brackets on a separate line, for example:
  [files]
Most sections consist of lines looking like
  name=value
or
  name=
  several lines of text
  =
The latter syntax is for cases when the //value// is a text of several lines.
In some sections, there is no //name// part because it’s implied.
If you type two ''=='' equal signs between the //name// and the //value// the latter will be handled as a regular expression.
Any line in the init part starting with a '';'' colon is ignored as a remark.

@s4[Sections of the Init Part]

Here is a brief listing of the sections. Detailed description follows below.
**FILES** to define the text files your book is contained in.
**SYNTAX** to define basic syntax elements.
**VARS** to set methods to extract information from the text of your book.
**MARKUP** to define the markup language you use.
**MACROS** to create macros that can perform more complex tasks.
**COUNTERS** to define counters to count instances of things.
In the descriptions, words written ''monospaced'' are the names to be used before an equal sign. All of them may be used several times, to define alternatives that all will be valid and usable.

@s4[The FILES Section]

This section lists URLs of text files containing your book, in the order they are supposed to appear in the book. No need to mention the very file containing the init part itself. This section may be omitted if that is the only file.
Each line is an URL like
  http://example.com/mybook/myfile.txt
Regular expressions aren’t allowed here, but instead, you can use shortcuts.
**Same Folder Shortcut.** If there are several files in the same folder, you can abbreviate it by typing a space character before the file name. This means “use the folder previously mentioned”. So, if the line above is followed by a line that reads
   otherfile.txt
it will actually mean ''http:/`/example.com/mybook/otherfile.txt''.
**Numbered Files Shortcut.** You can specify many files at once if they differ in a number only:
   myfile{1-100}.txt
This means you’ll include ''myfile1.txt'', ''myfile2.txt'' and so on. If any of the files is missing Nindish will skip it, supposing you allowed room for chapters to be written later.
If you use more than one numbered files shortcut in the same file name, it will be read from right to left, so:
   myfile{1-5}_{1-5}.txt
will add ''myfile1_1.txt'', ''myfile1_2.txt'' etc., ''myfile1_5.txt'' will be followed by ''myfile2_1.txt'' and so on. This can be useful for keeping track of numbered chapters and subchapters in respectively named files. However, this isn’t a requirement.
Instead of numbers, you can use letters, too:
   myfile{a-z}.txt
**Complete Folder Shortcut.** This will work only if you, the uploader of your files, enabled remote access. Ask your web hosting provider for more information. To use this feature, include an ''*'' asterisk in your URL, for example:
  http://example.com/mybook/*.txt
This will include any text file found in the folder. There must be no ''/'' character anywhere //after// the ''*'' character.

All files listed in the FILES section will be, in the order of mention, read and joined as a single text before any processing.

@s4[The SYNTAX Section]

The init part is the only part of your book where there is a fixed syntax to be followed. In this section, you define your own syntax to be used in the book part and Nindish will understand.

  * ''commandbegin'' and ''commandend'' Defines the symbols to be used in the book to recognize Nindish commands. For example,

  commandbegin={
  commandend=}
will tell Nindish that anything in between ''{'' and ''}'' is a Nindish command. These commands may be used both in the init part (the MACROS section) and in the book. The default values are the same as shown above.

  * ''content'' Defines the placeholder to be used for the content of a tag pair. The default value is ''||'' (two vertical bars), but you can change it with this variable. For example, when defining a title (see later), you can write

  title1=<title>||</title>
This means that you want to use the HTML tag ''<title>'' to mark the beginning of the title and ''</title>'' to mark the end of it. Everything in between will be the contents of the title.

  * ''content1'', ''content2'' etc. Additional placeholders for some commands. Default values are ''$1'', ''$2'' etc., respectively.

  * ''enter'' Defines a symbol for an Enter character. Default values are both ''\n'' and ''\r'' (no difference). For example:

  title1=\nTITLE ||\n
will define that the title is after a word TITLE separated from the preceding and following text by Enter characters, i.e. go on a separate line.

@s4[The VARS Section]

Things defined in this section will be stored in the database Nindish is using when processing your text. When the results of this process appears in your browser, the entire database is destroyed because Nindish builds it from scratch each time it is called, so all data is the newest.
These variables have no default values. If you leave any of them undefined, it won’t appear in the database and in the results.

  * ''author'' The author of the book. Supposed to be the actual name.
  * ''booktitle'' The main title of the book. Supposed to be the actual title.
  * ''charsonpage'' A number telling how many characters do you expect on a typical page. To obtain this number, render at least a typical page on the final format (with the page size, font size, margins and line spacing you want). Count how many lines a page has and how many characters a typical line has. Multiply the two numbers. If there is no final format where this may be applicable, you can omit this setting and related statistics won’t be displayed.
  * ''goalsize'' A number telling how long do you plan your finished book to be. After the number, enter ''l'' if the number is in letters, ''w'' if in words or ''p'' if in pages. If you didn’t decide how long your book is planned to be, skip this setting.
  * ''image'' The way to recognize an image in the book.
  * ''note'' The way to recognize a note in the book. Notes won’t appear in the finished book but can be referred to during working.
  * ''start'' The date you started to work on your book. Supposed to be the actual date in 8 digits, followed by a combination of eight letters ''y'', ''m'' and ''d'' (for example, ''20210628 yyyymmdd'') to let Nindish know what’s the order of the date. This is used for the statistics.
  * ''tag'' The way to recognize a tag in the book. It uses three placeholders, those defined as ''content1'', ''content2'' and ''content3''. ''Content1'' is the name of the tag. It will be displayed in the book where the tag was defined. ''Content2'' is the description. ''Content3'' is the category list. It’s recommended to define this variable for each possible cases:

  tag=[[$1]]
  tag=[[$1|$2]]
  tag=[[$1|$2|$3]]
  tag=[[$1||$3]]

  * ''tagabc'' Defines the alphabet to be used for tags. The format is the following:

  tagabc=letters, letters, letters
and so on. Each //letters// is a group of one or more letters or letter combinations, separated by spaces. Each letter in the same group is treated equal. For example: ''a á, b, c, cs, d, dz, dzs, e é'' etc. defines a Hungarian alphabet where //a// and //á// are the same letter in terms of alphabetical sorting, and so are //e// and //é;// meanwhile, //cs, dz// and //dzs// are all separate letters.
  * ''tagname'' The same as ''tag'' but for personal names that are written the Western way. In ''content1'' (the name), type a ''!'' before the surname. Then Nindish will record the name by swapping the order of the part before the ''!'' and after it, and adding a comma in between: ''Mario !Vargas Llosa'' will be tagged as //Vargas Llosa, Mario.// In the displayed book, the ''!'' character is simply removed.
  * ''tagnote'' The same as ''tag'' but ''content1'' will not be displayed in the book.
  * ''timestamp'' Defines the way to recognize a timestamp in the book. A timestamp tells when does the events at that point happen.
  * ''title1'', ''title2'' etc. The way to recognize a title in the book. ''Title1'' is of the highest rank. Any subchapter will belong to the chapter previously encountered to. For example:

  title1=<h1>||</h1>
will tell Nindish if later, in the book, it encounters a piece of text that goes, say,
  <h1>Preface</h1>
then it must take “Preface” a title of rank 1.
You can also use ''title'' with no number if there are no subchapters.

  * ''anything else'' (Don’t type, literally, “anything else”. Type any word you like.) To define a special collection, give it any name and define a way to recognize it. For example,

  quote=«||»
will create a collection called ''quote'' and fill it with all pieces of text that appear between marks « and ».
You can also use numbered ''content1'' etc. placeholders. In this case, the information extracted will be stored according to ''content1'' with all the other fields attached. For example,
  quote=“$2” ($1)
is a definition that will match
  “The purpose of our life is to be happy.” (Dalai Lama)
and the information will be stored in the collection ''quote'' under the name ''Dalai Lama''.

@s4[The MARKUP Section]

This section defines symbols you intend to use in your book and the way to translate them when displaying your text and rendering it into different output formats. This section uses a different syntax since you can define multiple languages at once. An entry in this section is required to be several lines long. Its structure looks like:
  markup description
  (name of language 1)
  output
  (name of language 2)
  output
  ()
Here, //markup description// is a regular expression in PHP syntax, on a separate line. Then one or more language descriptions follow, each beginning with the //name of language// in ''( )'' round parentheses on a separate line and the //output// description to tell Nindish what to translate that markup into when creating output in that language. An empty pair of parentheses mark the end of the listings belonging to this //markup description.//
For example,
  $(.*?)$
  (html)
  <b>$1</b>
  (bbcode)
  [b]$1[/b]
  (wiki)
  **$1**
  ()
This tells Nindish that when a piece of text is encountered between two ''$'' characters (because this is your private, unique choice to mark bold text), it should be translated to HTML language with placing it between the tags for bold, to BBCode with the tags used in that language etc. One of these languages, ''(html)'' is handled by Nindish itself when displaying your book in your browser. Any of the others will be used only when you select that language for output.
You can define any language with any name. In practice, probably you’ll need two: ''(html)'' to control the display in your browser and another one to create preformatted output for your word processor that builds the finished book.

@s4[The MACROS Section]

This section works similarly to the MARKUP section in terms that it modifies the source text. But there are no subsections for different markup languages here, it’s acting the same for all output. And you can use the Nindish macro commands.
Recognizing the commands is done by using the names ''commandbegin'' and ''commandend'' in the SYNTAX section. In the examples, I’ll use the default ''{ }'' marking.
The MACROS section defines your macros. In the book, you can use both these macros and any Nindish macro command.
  name parameters
  macro definition
  ()
This is how to define a macro. On the first row, you give it a name and (after a space) define any parameters, optionally. For example:
  roll n
This introduces a macro that’s called ''roll'' and it will have a parameter called ''n''. Further on, you can call it with ''{roll 6}'', for example, and this means that the value of ''n'' will be 6 at the beginning of the macro execution.
The macro definition may contain any text that’ll be inserted in the text at the place where the macro was called. For example,
  address
  Professor Michael Example
  4813 Example Drive, No Matter Where, California
  ()
This is a simple abbreviation for a longer text (which may even contain formatting of course). Entering ''{address}'' after this will result in the whole address to appear instead.
The macro definition can contain commands that are executed when the macro is called.

@s3[Macro Commands]

@s2[Variable Handling]

''let variable value''
Assigns a //value// to a //variable.// The value can be a literal or an expression resulting in either numeric or string data.
''var variable''
Gives the value of the //variable.// This is needed only if you want the value printed into your text. In expressions, you needn’t this.
''inc variable amount''
''dec variable amount''
Increases or decreases the //variable// by the given //amount.// If the amount is not specified, it defaults to 1.

@s2[Control of Execution]

''if expression''
''else''
''endif''
If the //expression// gives a value other than zero, the part between ''if'' and ''else'' is executed. Otherwise, the part between ''else'' and ''endif'' is executed.
''for variable start, end, step''
''next''
Creates a loop, repeating everything between ''for'' and ''next''. //Start// and //end// are expressions that specify the first and last values the //variable// will take. If //step// is not specified, it defaults to 1 if //start<end// or –1 if //start>end.// The three expressions must be separated by commas to let Nindish know where does each one end and the other one start.
''return value''
Quits the execution of a macro, returning the //value// to the place (another macro or the text of the book) that called it. The //value// will appear in the rendered text instead of the macro calling.
''name parameters''
To call another macro from a macro, you do the same as when calling them from the text: type its name and parameters required.

@s3[Expressions]

An expression is a set of values connected with operators. A value can be a number, a character string enclosed in ''"'' quotation marks, a variable name or a function.

@s4[The COUNTERS Section]

This section lists counters. A counter is something that counts the instances of things in the book. To define a counter, use
  name options=regular expression
The //options// may include ''null1'', ''null2'' etc. which tell Nindish to reset the counter to zero each time a title of the given or higher rank is encountered.

@s4[The END Section]

If you begin your book in the same file after the init part, finish the init part with a line that reads:
  [end]
If the init part is in a separate file, you don’t need this.

@s5[The Book Part]

Everything after the init part (in the same file and in the ones listed in the FILES section, in this order) is your book. These need to be Unicode plaintext files, and you can use any markup language (HTML, CSS, Wiki, BBCode, Markdown etc.), including any you invent for your book yourself. There is no limit. You can create markups for all the styles and formatting you are using.

@s6[Running Nindish]

To run Nindish, as mentioned before, you need to upload your files and enter the URL of Nindish in your browser. For first, the following will happen:
  * if you didn’t specify the URL of the init part, you’ll be prompted for that;
  * if you did specify the URL but not any option switches, the main page will appear, with data about your book;
  * if gave both the URL and some option switches, an additional page will appear, with more data about your book.
All links on Nindish pages lead to other Nindish pages, keeping the URL of your book and any switches you need further on.

@s5[The Main Page]

The main page lists the statistics on your book:
  * any counter you had defined;
  * the calculated length of your book, in characters (i.e. //including// the formatting characters), letters (//excluding// the formatting characters), words and pages (calculated using the ''charsonpage'' setting; real size of title formatting, tables, images etc. cannot be taken into account, so the more of such things, the greater the difference between this estimate and reality);
  * the number of tags, notes, special collection entries, images you have;
  * the days counted since you began working;
  * the number of letters, words and pages you write a day, averaging;
  * the expected date when you will finish your book, reaching the ''goalsize'' you entered.

@s5[The Contents Page]

The Contents page lists all the titles in your book, according the markup you gave for titles. For each title, it lists
  * the position of the title in the book (calculated page number);
  * the size of the text in the chapter (between the title and the next title of the same rank);
  * any counters belonging to the chapter.

@s5[The Tags Page]

First, you have an alphabetical index of your tags, complete with tag categories, if any. Each comma-separated entry in the ''tagabc'' variable and each category is turned into a separate page that lists tags belonging there. Note that a tag may belong to more categories.
Tags are displayed along with
  * their descriptions;
  * additional categories they belong to, beyond the one we are currently listing;
  * the position the tag is appearing at.
The same tag can appear multiple times in the text, with different descriptions and, if needed, different categories. You may specify some categories at either instance of the tag, other categories at another instance, and the tag will belong to all categories at least once mentioned.
Notes and special collections appear in the same format as tags.

@s5[The Timeline Page]

The timeline is a listing of events marked with timestamps. You can select which part of the timeline do you need.

@s5[The Images Page]

The Images page lists all images you called for in the book, with their URLs and positions. If they’re accessible, the images will appear themselves, too.

@s5[The Rendering Page]

The Rendering page will let you render any part of the book in any of the markup languages you’ve defined. For Word, PDF etc. document creation, it’s recommended to define HTML with CSS styling, in a way that you word processor can understand it.

@blogf[számtech irodalom]