Linus Torvalds`use asciidoc

2.19: web.adda/markup/Linus Torvalds`use asciidoc:
summary:
. my programming language, adda,
includes a markup language
so that simple ascii documentation
can be converted to html with advanced features
like hyperlinks, and formatting .
. xml and html code is written in ascii
but it's not as readable by humans
since it's designed primarily for machines .
. Linus Torvalds was famous for
condemning xml and supporting asciidoc
so I became interested in studying asciidoc
and incorporating parts of that into adda markup .
. there is an asciidoc renderer for Chrome OS .

adda markup's conflicts with ini format

10.25: news.adda/markup/conflicts with ini format:
. bzr (the ubuntu team's distrib'd cvs)
uses an ini folder with the catgories of
[/] and [groups] .
. generally the ini format can
conflict with the adda markup lang's syntax
because it uses brackets as category headers,
and the category name may consist of a single symbol character .

markup and toc mirroring

5.11: 5.31: adda/markup/integrated markup:
. I had thought of the markup lang' as being
part of the editor -- just as html
is considered to be part a browser --
but in keeping with the one-lang philosophy,
the programming lang should include the
markup lang' -- meta-level lang,
as well as assembly -- low-level lang .
. these levels can have unique syntax
yet share as many qualities as possible .
. by being part of the same standard,
they are all easier to use and remember;
and by not leaving a mode out,
you avoid forcing people to roll their own;
of course, if that's their interest,
good openware should make it easier to do
by providing a reusable kit .]
5.11: adda/markup/toc mirroring:
. there are 2 ways to express nested subtitles:
# containers:
. the markup lang' has container tags:
-- subtitle: [(], [)] --
all titles within the container
are nested within the container's title;
nested titles shows up in the toc as being
indented deeper than their enclosure's title .
# toc's:
. the table of contents (toc) is auto-generated
from what is marked up as being subtitles;
conversely,
if the toc's indentation is changed;
the documents markup will be auto-adjusted
to actively reflect the toc's state,
and auto-generate container markup .

adda's subfile support

7.17: adda/subfile support:
. adda can use adde ml to define subfiles
and can also treat any of html's
hierarchical structures as subfiles .
[7.27: intro:
. the idea of subfiles as chunks of text,
is to have an documents arranged like
folder trees of files
without depending on the platform's
native folder and file system .
. files usually contain several subfiles,
and in this way act as folders .
. conversely, a folder of files
may be identified as one document .
. how subfiles are packed into files
depends on how the subfiles are used:
documents that are frequently modified
will be packed into more files .
. very large doc's will be packed into
more folders .
. adde ml (markup language) is a
simplified form of html that uses
an exclamation point in brackets
as an escape for text about text,
such as identifying the title of a subfile .]

xml modeling

3.26: adda/xml modeling:
. the basics of xml started with
putting "(br) -- line break -- in angle-brackets;
because, angle brackets classically mean
a formal parameter,
as seen in language syntax diagrams .
. this formalism was required because
-- despite their being a standard for text --
there was no unambiguous representation for
line structure: { cr, lf, cr-lf, line's char count } .
. another (incidental) property was that
angle brackets were separating text that was
not meant to be taken literally;
and, this was the basis for
extending the use of angle brackets
for any text that was not to be taken literally .
. the basic structure of {sgml, html, xml}
is to have a pair of angle brackets for
each opening and closing element .
. using that way, there's a restriction on
literal text containing angle brackets;
whereas,
with a parenthetical method (described next)
there's a restriction only on
un-paired parentheses, and the use of the
code-starting symbol: [!]
which can be chosen to be both
very rare in literal text
and easy to write, read, and find .
. the math-english way would have made use
of parenthetical symbols:
{literal text ...}
[!]
block-name( parameters,,, ):
(
{literal text ...}
)-block-name
[!]
non-block ( parameters,,,)
{literal text ...}
3.31:
. the lisp way is slightly more compact:
{literal text ...}
[!]
(block-name parameters,,, :
{literal text ...}
)-block-name
[!]
(non-block-name parameters,,,)
{literal text ...} .

footnotes

7.6:

. the purpose of adde`markup

is to have language that functions like html

but is a little easier to read and write .

. hyperlinks are prefixed by [@]

and in-line code is prefixed by [!]

7.6: adde/markup/perhaps obsolete?:

. markup is sort of an obsolete idea,

as the editor should be smartly helping you markup with a gui,

and then encoding the markup with wordcode

so that markup is a form of etree (ast) .

... then again:

. markup is not obs' because there should be

an ascii representation for all etrees;

[12.16: because,

the realities may require at some point

the use of a plain text editor;

eg, viewing work on pda's and e'book readers

for which addx is not yet available or not allowed .

]

6.12:

. footnotes are like hyperlinks,

so they should use the word[@]link syntax,

but instead of cluttering up the sentence,

it should use a sort of footnoting,

where the link info is deferred to the end

of the sentence, paragraph, or page .

7.7:

. here is a discrete way to do both hyperlinks and footnotes:

[((phrase to footmark))][]

. the box [] tells you that the previous lexical element

is a deferred link,

so then at the end of the line or paragraph

there is the "([@] { ...}) showing the list of footnotes .

. they are matched 1-to-1,

so that the nth [] is linked to the nth item in the [@]-list .

12.16:

. one problem ignored by the above idea

is that a good markup language will rarely conflict with

the language it's embedded in;

eg, you'll see "([]) a lot in c code .