Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation for xml format #13

Open
LBroe opened this issue Jun 3, 2022 · 10 comments
Open

Documentation for xml format #13

LBroe opened this issue Jun 3, 2022 · 10 comments

Comments

@LBroe
Copy link

LBroe commented Jun 3, 2022

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
Copy link

tscales commented Jun 3, 2022

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
Copy link

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>

image
image
image
image

@aseaday
Copy link

aseaday commented Jun 6, 2022

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
Copy link
Author

LBroe commented Jun 6, 2022

@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
Copy link

aseaday commented Jun 6, 2022 via email

@LBroe
Copy link
Author

LBroe commented Jun 6, 2022

@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
Copy link

How about Gitbook.

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

@aseaday
Copy link

aseaday commented Jun 6, 2022

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

@aseaday
Copy link

aseaday commented Jun 6, 2022

@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
Copy link
Owner

mxgmn commented Jun 7, 2022 •
edited

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@aseaday @inkydragon @tscales @mxgmn @LBroe