Documentation for xml format

[LBroe]

I'd love some documentation about the syntax of the model XML files. At the moment we can only deduce the nodes and parameters from the examples.

[tscales]

The node factory is a good place to start, These will be your toplevel elements.

MarkovJunior/source/Node.cs

Lines 24 to 38 in 222cd2e

	Node result = xelem.Name.LocalName switch
	{
	"one" => new OneNode(),
	"all" => new AllNode(),
	"prl" => new ParallelNode(),
	"markov" => new MarkovNode(),
	"sequence" => new SequenceNode(),
	"path" => new PathNode(),
	"map" => new MapNode(),
	"convolution" => new ConvolutionNode(),
	"convchain" => new ConvChainNode(),
	"wfc" when xelem.Get<string>("sample", null) != null => new OverlapNode(),
	"wfc" when xelem.Get<string>("tileset", null) != null => new TileNode(),
	_ => null
	};

Each node has a Load method which should help deduce what nested elements the node is expecting.

[inkydragon]

I'm trying to write xsd definitions for xml files.
It looks like VS can automatically load the xsd and display popups.
Of course it is also important to write human-readable documentation.

Some attempts (remarks may not be accurate):

models.xsd

put this at docs/models.xsd

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="models">
        <xs:complexType mixed="true">
            <xs:sequence>
                <xs:element name="model" maxOccurs="unbounded">
                    <xs:complexType>
                        <xs:attribute name="name" type="xs:string" use="required">
                            <xs:annotation>
                                <xs:documentation>Model xml file name.

File `$"models/{name}.xml"` should exist.
</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="size" default="-1" type="xs:int" use="optional">
                            <xs:annotation>
                                <xs:documentation>Output Size in Pixel. default=-1

Note: If `size` is not specified, then `widht` and `hight` should be specified.</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="d" default="2" use="optional">
                            <xs:annotation>
                                <xs:documentation>Output dimension. [2, 3] default=2</xs:documentation>
                            </xs:annotation>
                            <xs:simpleType>
                                <xs:restriction base="xs:positiveInteger">
                                    <xs:enumeration value="2" />
                                    <xs:enumeration value="3" />
                                </xs:restriction>
                            </xs:simpleType>
                        </xs:attribute>
                        <xs:attribute name="length" type="xs:positiveInteger" use="optional">
                            <xs:annotation>
                                <xs:documentation>X-axis length. default=size</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="width" type="xs:positiveInteger" use="optional">
                            <xs:annotation>
                                <xs:documentation>Y-axis width. default=size</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="height" type="xs:positiveInteger" use="optional">
                            <xs:annotation>
                                <xs:documentation>Z-axis height.

2D (d==2), default=1;
3D (d==3), default=size;
</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="amount" default="2" type="xs:positiveInteger" use="optional">
                            <xs:annotation>
                                <xs:documentation>Number of output files. default=2</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="pixelsize" default="4" type="xs:positiveInteger" use="optional">
                            <xs:annotation>
                                <xs:documentation>Pixel point size. default=4</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="seeds" default="null" type="xs:string" use="optional">
                            <xs:annotation>
                                <xs:documentation>Random number seed list. default=null</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="gif" default="false" type="xs:boolean" use="optional">
                            <xs:annotation>
                                <xs:documentation>Whether to output gifs. default=false</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="iso" default="false" type="xs:boolean" use="optional">
                            <xs:annotation>
                                <xs:documentation>Whether to output in `iso` format. default=false</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="steps" default="1000" type="xs:int" use="optional">
                            <xs:annotation>
                                <xs:documentation>Number of rule execution steps. 

GIF (gif==true), default=1000;
Others (gif==false), default=50000;</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="gui" default="0" type="xs:nonNegativeInteger" use="optional">
                            <xs:annotation>
                                <xs:documentation>The width of the graphical rule sidebar in the output image. 
default=0 (not show)</xs:documentation>
                            </xs:annotation>
                        </xs:attribute>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

[lalawuu]

Hi, I am working on a port of Markov Junior project. And I am considering to create a doc for this project. What syntax doc format do you prefer or recommend?

[LBroe]

@aseaday It's supposed to be a programming language, so we need a description of how to write a program with it. What are the keywords and how does the control flow work? I'd just start with a markdown file, because that is the most accessible format.

[lalawuu]

How about Gitbook. I think the syntaxs is not the first grasp of user's attentions. Maybe an introuction about what is markov generatation and more detailed guide woule useful. @mxgmn, Are you ok to open a repo about docs?

…

________________________________________ 发件人: Leon Bröckers ***@***.***> 发送时间: 2022年6月6日 14:29 收件人: mxgmn/MarkovJunior 抄送: nullday; Mention 主题: Re: [mxgmn/MarkovJunior] Documentation for xml format (Issue #13) @aseaday<https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Faseaday&data=05%7C01%7C%7Caca9014371e1432959eb08da4785e598%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637900937661024852%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=WF1Hwza6ksuBrKFsxSE1sIlninG%2FzW8UciBQc2wRs2E%3D&reserved=0> It's supposed to be a programming language, so we need a description of how to write a program with it. What are the keywords and how does the control flow work? I'd just start with a markdown file, because that is the most accessible format. — Reply to this email directly, view it on GitHub<https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fmxgmn%2FMarkovJunior%2Fissues%2F13%23issuecomment-1147095861&data=05%7C01%7C%7Caca9014371e1432959eb08da4785e598%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637900937661024852%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=ZEMC6hlYzIx1gAbATg4QuamXDvzoGgOvOctDIO%2FIcDU%3D&reserved=0>, or unsubscribe<https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAA562O6DDMD5YQRFWD2IDKDVNWLEHANCNFSM5XYDBN3A&data=05%7C01%7C%7Caca9014371e1432959eb08da4785e598%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637900937661024852%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=JjPF5EEWo9rnpBm1FMMtLB34G7ZWwY0d9hd0bo9AVFY%3D&reserved=0>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[LBroe]

@aseaday But the syntax is exactly what's missing. We already have a long and thorough readme with links to further information. We just don't know how to write a program with this programming language.

[inkydragon]

How about Gitbook.

I would recommend GitHub pages.
We can write some md documentation first and then decide how to deploy it.

[lalawuu]

How about we talk in Documentation and resources #24.
I think we could formally do this thing as a team.

[lalawuu]

@aseaday But the syntax is exactly what's missing. We already have a long and thorough readme with links to further information. We just don't know how to write a program with this programming language.

I got you. The explanation of node type and there combination rule is missing.

[mxgmn]

I have started writing about xml syntax in syntax.md. Hope this helps!