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.

https://github.com/mxgmn/MarkovJunior/blob/222cd2eec0d726ef1772a906532cb06036f7f453/source/Node.cs#L24-L38

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>

[aseaday]

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.

[aseaday]

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)

@aseadayhttps://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 GitHubhttps://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 unsubscribehttps://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.

[aseaday]

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

[aseaday]

@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!