I think it could be time to move on, but it looks like a big job to move to a different format. I think two
things are essential:

1. easy to edit and to add reference pages
2. easy to render to all formats we need (plus others as a bonus)

I think leading this change is probably a job for whoever takes on as editor.
========================
Prof. Victor Lazzarini
Maynooth University
Ireland

> On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
>
> I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
>
> On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> On 30.09.19 11:28, Victor Lazzarini wrote:
> > Good resolutions. A few comments from me.
> >
> > 1. We need a manual editor/maintainer. François has been kindly building the
> > releases, but I think we do not have anyone leading editorial decisions and
> > organising the manual. All the things listed there need quite a bit of work and
> > the reason they have not been done is because no one is taking the editor’s
> > job. That should be a recognised position, and named at the top of the manual,
> > e.g.
> >
> > Csound Reference Manual
> > Jane Doe, Editor
> >
> > and a recognised publication, possibly with DOI etc. that we can cite.
>
> Would it be thinkable to convert the manual to a different format?
> docbook takes really too long to build and there does not seem to be any
> way to parallelize it. There is also a lot of manual indexing involved
> that could be automated (adding an opcode to a specific category, adding
> it to the global list of opcodes, etc)
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here
> Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here


Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Also an important issue is that a number of tools are built around the
documentation. I know Blue uses a python script to read the
documentation as XML and generate information it uses for syntax
highlighting and presenting of opcode information to the user.  Also,
I depend upon the HTML output organization with opcode entries going
to files with [opcodename].html.  I think CsoundQt and Cabbage may be
in the same boat, perhaps others.

This is to say that the documentation is not just a format for output
to the print/screen manual, but also a data source too.  I'm all for
transitioning the documentation to a new format as long as we also
keep the data aspect in mind.

On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>
> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
> things are essential:
>
> 1. easy to edit and to add reference pages
> 2. easy to render to all formats we need (plus others as a bonus)
>
> I think leading this change is probably a job for whoever takes on as editor.
> ========================
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
> >
> > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
> >
> > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> > On 30.09.19 11:28, Victor Lazzarini wrote:
> > > Good resolutions. A few comments from me.
> > >
> > > 1. We need a manual editor/maintainer. François has been kindly building the
> > > releases, but I think we do not have anyone leading editorial decisions and
> > > organising the manual. All the things listed there need quite a bit of work and
> > > the reason they have not been done is because no one is taking the editor’s
> > > job. That should be a recognised position, and named at the top of the manual,
> > > e.g.
> > >
> > > Csound Reference Manual
> > > Jane Doe, Editor
> > >
> > > and a recognised publication, possibly with DOI etc. that we can cite.
> >
> > Would it be thinkable to convert the manual to a different format?
> > docbook takes really too long to build and there does not seem to be any
> > way to parallelize it. There is also a lot of manual indexing involved
> > that could be automated (adding an opcode to a specific category, adding
> > it to the global list of opcodes, etc)
> >
> > Csound mailing list
> > Csound@listserv.heanet.ie
> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> > Send bugs reports to
> >         https://github.com/csound/csound/issues
> > Discussions of bugs and features can be posted here
> > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Thanks, that’s another one to try. I have the impression we have the manual in docbook since early 2000s. Definitely
since Csound 5 (2003), so it has lasted for about 20 years.
========================
Prof. Victor Lazzarini
Maynooth University
Ireland

> On 1 Oct 2019, at 10:01, Eduardo Moguillansky <eduardo.moguillansky@GMAIL.COM> wrote:
>
> I have had a very nice experience with the csound plugins documentation, written in mkdocs:
>
> * source: https://github.com/csound-plugins/csound-plugins/tree/master/docs
> * online version: https://csound-plugins.github.io/csound-plugins/
>
> Features:
>
> * Each page is written in markdown
> * it has csound syntax highlighting
> * examples can be placed inline
> * as it is markdown it can be read as is
> * the manual compiles in seconds to html
> * other formats for export are supported (pdf)
> * the markdown itself can be easily parsed by thirdparty tools to extract information
> * the generated html can be used offline (either just opening index.html or mkdocs can act as server which enables search within the whole pages, as in the online version)
>
> On the negative side, I am not sure if mkdocs will be around in 10 years, but I am also not so optimistic about many other things still being around in 10 years...
>
>
>
> On 01.10.19 10:39, Victor Lazzarini wrote:
>> All those things are important to take in consideration.
>>
>> From a manual page writing perspective, which is the most contact I had with the manual, the
>> most problematic thing is markup verbosity and the strict syntax of the tags. Otherwise, I’d
>> be happy to continue as it is, any other inconvenience is minor.
>>
>> What would I like to see, from the perspective of a manual page writer:
>>
>> 1. Plain text format, editable anywhere
>> 2. Low level of formatting annotation
>> 3. Easy placement of examples (all in one, no need to produce separate CSDs)
>> 4. Readability
>> 5. No need to edit main manual to insert pages.
>>
>> As an example, this is the type of workflow I see would be very handy
>>
>> 1. Open editor of choice.
>> 2. Type the manual page using markdown-like annotations.
>> 3. Add example directly to text.
>> 4. Save it to relevant source folder.
>> 5. Compile the manual.
>>
>> ========================
>> Prof. Victor Lazzarini
>> Maynooth University
>> Ireland
>>
>>> On 30 Sep 2019, at 15:37, Steven Yi <stevenyi@gmail.com> wrote:
>>>
>>> Also an important issue is that a number of tools are built around the
>>> documentation. I know Blue uses a python script to read the
>>> documentation as XML and generate information it uses for syntax
>>> highlighting and presenting of opcode information to the user.  Also,
>>> I depend upon the HTML output organization with opcode entries going
>>> to files with [opcodename].html.  I think CsoundQt and Cabbage may be
>>> in the same boat, perhaps others.
>>>
>>> This is to say that the documentation is not just a format for output
>>> to the print/screen manual, but also a data source too.  I'm all for
>>> transitioning the documentation to a new format as long as we also
>>> keep the data aspect in mind.
>>>
>>> On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>>>> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
>>>> things are essential:
>>>>
>>>> 1. easy to edit and to add reference pages
>>>> 2. easy to render to all formats we need (plus others as a bonus)
>>>>
>>>> I think leading this change is probably a job for whoever takes on as editor.
>>>> ========================
>>>> Prof. Victor Lazzarini
>>>> Maynooth University
>>>> Ireland
>>>>
>>>>> On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
>>>>>
>>>>> I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
>>>>>
>>>>> On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
>>>>> On 30.09.19 11:28, Victor Lazzarini wrote:
>>>>>> Good resolutions. A few comments from me.
>>>>>>
>>>>>> 1. We need a manual editor/maintainer. François has been kindly building the
>>>>>> releases, but I think we do not have anyone leading editorial decisions and
>>>>>> organising the manual. All the things listed there need quite a bit of work and
>>>>>> the reason they have not been done is because no one is taking the editor’s
>>>>>> job. That should be a recognised position, and named at the top of the manual,
>>>>>> e.g.
>>>>>>
>>>>>> Csound Reference Manual
>>>>>> Jane Doe, Editor
>>>>>>
>>>>>> and a recognised publication, possibly with DOI etc. that we can cite.
>>>>> Would it be thinkable to convert the manual to a different format?
>>>>> docbook takes really too long to build and there does not seem to be any
>>>>> way to parallelize it. There is also a lot of manual indexing involved
>>>>> that could be automated (adding an opcode to a specific category, adding
>>>>> it to the global list of opcodes, etc)
>>>>>
>>>>> Csound mailing list
>>>>> Csound@listserv.heanet.ie
>>>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>>>> Send bugs reports to
>>>>>        https://github.com/csound/csound/issues
>>>>> Discussions of bugs and features can be posted here
>>>>> Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>>>>
>>>> Csound mailing list
>>>> Csound@listserv.heanet.ie
>>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>>> Send bugs reports to
>>>>        https://github.com/csound/csound/issues
>>>> Discussions of bugs and features can be posted here
>>> Csound mailing list
>>> Csound@listserv.heanet.ie
>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> Send bugs reports to
>>>        https://github.com/csound/csound/issues
>>> Discussions of bugs and features can be posted here
>>
>> Csound mailing list
>> Csound@listserv.heanet.ie
>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>> Send bugs reports to
>>         https://github.com/csound/csound/issues
>> Discussions of bugs and features can be posted here
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>       https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here


Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

For now, how does one submit proposed changes to the manual? [Docbook does not seem to be an editor-friendly format!]

On Tue, Oct 1, 2019 at 2:26 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:

Thanks, that’s another one to try. I have the impression we have the manual in docbook since early 2000s. Definitely
since Csound 5 (2003), so it has lasted for about 20 years.
========================
Prof. Victor Lazzarini
Maynooth University
Ireland

> On 1 Oct 2019, at 10:01, Eduardo Moguillansky <eduardo.moguillansky@GMAIL.COM> wrote:
>
> I have had a very nice experience with the csound plugins documentation, written in mkdocs:
>
> * source: https://github.com/csound-plugins/csound-plugins/tree/master/docs
> * online version: https://csound-plugins.github.io/csound-plugins/
>
> Features:
>
> * Each page is written in markdown
> * it has csound syntax highlighting
> * examples can be placed inline
> * as it is markdown it can be read as is
> * the manual compiles in seconds to html
> * other formats for export are supported (pdf)
> * the markdown itself can be easily parsed by thirdparty tools to extract information
> * the generated html can be used offline (either just opening index.html or mkdocs can act as server which enables search within the whole pages, as in the online version)
>
> On the negative side, I am not sure if mkdocs will be around in 10 years, but I am also not so optimistic about many other things still being around in 10 years...
>
>
>
> On 01.10.19 10:39, Victor Lazzarini wrote:
>> All those things are important to take in consideration.
>>
>> From a manual page writing perspective, which is the most contact I had with the manual, the
>> most problematic thing is markup verbosity and the strict syntax of the tags. Otherwise, I’d
>> be happy to continue as it is, any other inconvenience is minor.
>>
>> What would I like to see, from the perspective of a manual page writer:
>>
>> 1. Plain text format, editable anywhere
>> 2. Low level of formatting annotation
>> 3. Easy placement of examples (all in one, no need to produce separate CSDs)
>> 4. Readability
>> 5. No need to edit main manual to insert pages.
>>
>> As an example, this is the type of workflow I see would be very handy
>>
>> 1. Open editor of choice.
>> 2. Type the manual page using markdown-like annotations.
>> 3. Add example directly to text.
>> 4. Save it to relevant source folder.
>> 5. Compile the manual.
>>
>> ========================
>> Prof. Victor Lazzarini
>> Maynooth University
>> Ireland
>>
>>> On 30 Sep 2019, at 15:37, Steven Yi <stevenyi@gmail.com> wrote:
>>>
>>> Also an important issue is that a number of tools are built around the
>>> documentation. I know Blue uses a python script to read the
>>> documentation as XML and generate information it uses for syntax
>>> highlighting and presenting of opcode information to the user.  Also,
>>> I depend upon the HTML output organization with opcode entries going
>>> to files with [opcodename].html.  I think CsoundQt and Cabbage may be
>>> in the same boat, perhaps others.
>>>
>>> This is to say that the documentation is not just a format for output
>>> to the print/screen manual, but also a data source too.  I'm all for
>>> transitioning the documentation to a new format as long as we also
>>> keep the data aspect in mind.
>>>
>>> On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>>>> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
>>>> things are essential:
>>>>
>>>> 1. easy to edit and to add reference pages
>>>> 2. easy to render to all formats we need (plus others as a bonus)
>>>>
>>>> I think leading this change is probably a job for whoever takes on as editor.
>>>> ========================
>>>> Prof. Victor Lazzarini
>>>> Maynooth University
>>>> Ireland
>>>>
>>>>> On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
>>>>>
>>>>> I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
>>>>>
>>>>> On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
>>>>> On 30.09.19 11:28, Victor Lazzarini wrote:
>>>>>> Good resolutions. A few comments from me.
>>>>>>
>>>>>> 1. We need a manual editor/maintainer. François has been kindly building the
>>>>>> releases, but I think we do not have anyone leading editorial decisions and
>>>>>> organising the manual. All the things listed there need quite a bit of work and
>>>>>> the reason they have not been done is because no one is taking the editor’s
>>>>>> job. That should be a recognised position, and named at the top of the manual,
>>>>>> e.g.
>>>>>>
>>>>>> Csound Reference Manual
>>>>>> Jane Doe, Editor
>>>>>>
>>>>>> and a recognised publication, possibly with DOI etc. that we can cite.
>>>>> Would it be thinkable to convert the manual to a different format?
>>>>> docbook takes really too long to build and there does not seem to be any
>>>>> way to parallelize it. There is also a lot of manual indexing involved
>>>>> that could be automated (adding an opcode to a specific category, adding
>>>>> it to the global list of opcodes, etc)
>>>>>
>>>>> Csound mailing list
>>>>> Csound@listserv.heanet.ie
>>>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>>>> Send bugs reports to
>>>>>        https://github.com/csound/csound/issues
>>>>> Discussions of bugs and features can be posted here
>>>>> Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>>>>
>>>> Csound mailing list
>>>> Csound@listserv.heanet.ie
>>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>>> Send bugs reports to
>>>>        https://github.com/csound/csound/issues
>>>> Discussions of bugs and features can be posted here
>>> Csound mailing list
>>> Csound@listserv.heanet.ie
>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> Send bugs reports to
>>>        https://github.com/csound/csound/issues
>>> Discussions of bugs and features can be posted here
>>
>> Csound mailing list
>> Csound@listserv.heanet.ie
>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>> Send bugs reports to
>>         https://github.com/csound/csound/issues
>> Discussions of bugs and features can be posted here
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>       https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here


Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Rory's way s the rest but if the change is smaller isolated sending me a repaeet for or stuff or patch would probably work.

==John

⁣Sent from TypeApp ​

On Oct 1, 2019, 14:34, at 14:34, Rory Walsh <rorywalsh@ear.ie> wrote:
>What I usually do is clone the manual repo, make some changes, or
>create a
>new xml file depending on what I'm doing, and finally, submit a PR. I
>rarely actually ever try to build locally as it is a pain. The PR will
>trigger a build, and if there are no problems it will be accepted and
>become part of the next release.
>
>On Tue, 1 Oct 2019 at 14:16, Forrest Curo <treegestalt@gmail.com>
>wrote:
>
>> For now, how does one submit proposed changes to the manual? [Docbook
>does
>> not seem to be an editor-friendly format!]
>>
>> On Tue, Oct 1, 2019 at 2:26 AM Victor Lazzarini
><Victor.Lazzarini@mu.ie>
>> wrote:
>>
>>> Thanks, that’s another one to try. I have the impression we have the
>>> manual in docbook since early 2000s. Definitely
>>> since Csound 5 (2003), so it has lasted for about 20 years.
>>> ========================
>>> Prof. Victor Lazzarini
>>> Maynooth University
>>> Ireland
>>>
>>> > On 1 Oct 2019, at 10:01, Eduardo Moguillansky <
>>> eduardo.moguillansky@GMAIL.COM> wrote:
>>> >
>>> > I have had a very nice experience with the csound plugins
>>> documentation, written in mkdocs:
>>> >
>>> > * source:
>>> https://github.com/csound-plugins/csound-plugins/tree/master/docs
>>> > * online version: https://csound-plugins.github.io/csound-plugins/
>>> >
>>> > Features:
>>> >
>>> > * Each page is written in markdown
>>> > * it has csound syntax highlighting
>>> > * examples can be placed inline
>>> > * as it is markdown it can be read as is
>>> > * the manual compiles in seconds to html
>>> > * other formats for export are supported (pdf)
>>> > * the markdown itself can be easily parsed by thirdparty tools to
>>> extract information
>>> > * the generated html can be used offline (either just opening
>>> index.html or mkdocs can act as server which enables search within
>the
>>> whole pages, as in the online version)
>>> >
>>> > On the negative side, I am not sure if mkdocs will be around in 10
>>> years, but I am also not so optimistic about many other things still
>being
>>> around in 10 years...
>>> >
>>> >
>>> >
>>> > On 01.10.19 10:39, Victor Lazzarini wrote:
>>> >> All those things are important to take in consideration.
>>> >>
>>> >> From a manual page writing perspective, which is the most contact
>I
>>> had with the manual, the
>>> >> most problematic thing is markup verbosity and the strict syntax
>of
>>> the tags. Otherwise, I’d
>>> >> be happy to continue as it is, any other inconvenience is minor.
>>> >>
>>> >> What would I like to see, from the perspective of a manual page
>writer:
>>> >>
>>> >> 1. Plain text format, editable anywhere
>>> >> 2. Low level of formatting annotation
>>> >> 3. Easy placement of examples (all in one, no need to produce
>separate
>>> CSDs)
>>> >> 4. Readability
>>> >> 5. No need to edit main manual to insert pages.
>>> >>
>>> >> As an example, this is the type of workflow I see would be very
>handy
>>> >>
>>> >> 1. Open editor of choice.
>>> >> 2. Type the manual page using markdown-like annotations.
>>> >> 3. Add example directly to text.
>>> >> 4. Save it to relevant source folder.
>>> >> 5. Compile the manual.
>>> >>
>>> >> ========================
>>> >> Prof. Victor Lazzarini
>>> >> Maynooth University
>>> >> Ireland
>>> >>
>>> >>> On 30 Sep 2019, at 15:37, Steven Yi <stevenyi@gmail.com> wrote:
>>> >>>
>>> >>> Also an important issue is that a number of tools are built
>around the
>>> >>> documentation. I know Blue uses a python script to read the
>>> >>> documentation as XML and generate information it uses for syntax
>>> >>> highlighting and presenting of opcode information to the user.
>Also,
>>> >>> I depend upon the HTML output organization with opcode entries
>going
>>> >>> to files with [opcodename].html.  I think CsoundQt and Cabbage
>may be
>>> >>> in the same boat, perhaps others.
>>> >>>
>>> >>> This is to say that the documentation is not just a format for
>output
>>> >>> to the print/screen manual, but also a data source too.  I'm all
>for
>>> >>> transitioning the documentation to a new format as long as we
>also
>>> >>> keep the data aspect in mind.
>>> >>>
>>> >>> On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <
>>> Victor.Lazzarini@mu.ie> wrote:
>>> >>>> I think it could be time to move on, but it looks like a big
>job to
>>> move to a different format. I think two
>>> >>>> things are essential:
>>> >>>>
>>> >>>> 1. easy to edit and to add reference pages
>>> >>>> 2. easy to render to all formats we need (plus others as a
>bonus)
>>> >>>>
>>> >>>> I think leading this change is probably a job for whoever takes
>on
>>> as editor.
>>> >>>> ========================
>>> >>>> Prof. Victor Lazzarini
>>> >>>> Maynooth University
>>> >>>> Ireland
>>> >>>>
>>> >>>>> On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson
><hlolli@gmail.com>
>>> wrote:
>>> >>>>>
>>> >>>>> I discussed it with some people, that it makes sense to go for
>>> another format than docbook. Could be json, yaml or even python
>dictionary.
>>> From a more programmating format its easy to render various formats.
>As
>>> well, for front ends to generate syntax highlighting and minidocs.
>XML is
>>> becoming too arcane imo.
>>> >>>>>
>>> >>>>> On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <
>>> eduardo.moguillansky@gmail.com> wrote:
>>> >>>>> On 30.09.19 11:28, Victor Lazzarini wrote:
>>> >>>>>> Good resolutions. A few comments from me.
>>> >>>>>>
>>> >>>>>> 1. We need a manual editor/maintainer. François has been
>kindly
>>> building the
>>> >>>>>> releases, but I think we do not have anyone leading editorial
>>> decisions and
>>> >>>>>> organising the manual. All the things listed there need quite
>a
>>> bit of work and
>>> >>>>>> the reason they have not been done is because no one is
>taking the
>>> editor’s
>>> >>>>>> job. That should be a recognised position, and named at the
>top of
>>> the manual,
>>> >>>>>> e.g.
>>> >>>>>>
>>> >>>>>> Csound Reference Manual
>>> >>>>>> Jane Doe, Editor
>>> >>>>>>
>>> >>>>>> and a recognised publication, possibly with DOI etc. that we
>can
>>> cite.
>>> >>>>> Would it be thinkable to convert the manual to a different
>format?
>>> >>>>> docbook takes really too long to build and there does not seem
>to
>>> be any
>>> >>>>> way to parallelize it. There is also a lot of manual indexing
>>> involved
>>> >>>>> that could be automated (adding an opcode to a specific
>category,
>>> adding
>>> >>>>> it to the global list of opcodes, etc)
>>> >>>>>
>>> >>>>> Csound mailing list
>>> >>>>> Csound@listserv.heanet.ie
>>> >>>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> >>>>> Send bugs reports to
>>> >>>>>        https://github.com/csound/csound/issues
>>> >>>>> Discussions of bugs and features can be posted here
>>> >>>>> Csound mailing list Csound@listserv.heanet.ie
>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to
>>> https://github.com/csound/csound/issues Discussions of bugs and
>features
>>> can be posted here
>>> >>>>
>>> >>>> Csound mailing list
>>> >>>> Csound@listserv.heanet.ie
>>> >>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> >>>> Send bugs reports to
>>> >>>>        https://github.com/csound/csound/issues
>>> >>>> Discussions of bugs and features can be posted here
>>> >>> Csound mailing list
>>> >>> Csound@listserv.heanet.ie
>>> >>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> >>> Send bugs reports to
>>> >>>        https://github.com/csound/csound/issues
>>> >>> Discussions of bugs and features can be posted here
>>> >>
>>> >> Csound mailing list
>>> >> Csound@listserv.heanet.ie
>>> >> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> >> Send bugs reports to
>>> >>         https://github.com/csound/csound/issues
>>> >> Discussions of bugs and features can be posted here
>>> >
>>> > Csound mailing list
>>> > Csound@listserv.heanet.ie
>>> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> > Send bugs reports to
>>> >       https://github.com/csound/csound/issues
>>> > Discussions of bugs and features can be posted here
>>>
>>>
>>> Csound mailing list
>>> Csound@listserv.heanet.ie
>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> Send bugs reports to
>>>         https://github.com/csound/csound/issues
>>> Discussions of bugs and features can be posted here
>>>
>> Csound mailing list Csound@listserv.heanet.ie
>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to
>> https://github.com/csound/csound/issues Discussions of bugs and
>features
>> can be posted here
>
>Csound mailing list
>Csound@listserv.heanet.ie
>https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>Send bugs reports to
>        https://github.com/csound/csound/issues
>Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Thanks, that’s another one to try. I have the impression we have the manual in docbook since early 2000s. Definitely
since Csound 5 (2003), so it has lasted for about 20 years.
========================
Prof. Victor Lazzarini
Maynooth University
Ireland

> On 1 Oct 2019, at 10:01, Eduardo Moguillansky <eduardo.moguillansky@GMAIL.COM> wrote:
>
> I have had a very nice experience with the csound plugins documentation, written in mkdocs:
>
> * source: https://github.com/csound-plugins/csound-plugins/tree/master/docs
> * online version: https://csound-plugins.github.io/csound-plugins/
>
> Features:
>
> * Each page is written in markdown
> * it has csound syntax highlighting
> * examples can be placed inline
> * as it is markdown it can be read as is
> * the manual compiles in seconds to html
> * other formats for export are supported (pdf)
> * the markdown itself can be easily parsed by thirdparty tools to extract information
> * the generated html can be used offline (either just opening index.html or mkdocs can act as server which enables search within the whole pages, as in the online version)
>
> On the negative side, I am not sure if mkdocs will be around in 10 years, but I am also not so optimistic about many other things still being around in 10 years...
>
>
>
> On 01.10.19 10:39, Victor Lazzarini wrote:
>> All those things are important to take in consideration.
>>
>> From a manual page writing perspective, which is the most contact I had with the manual, the
>> most problematic thing is markup verbosity and the strict syntax of the tags. Otherwise, I’d
>> be happy to continue as it is, any other inconvenience is minor.
>>
>> What would I like to see, from the perspective of a manual page writer:
>>
>> 1. Plain text format, editable anywhere
>> 2. Low level of formatting annotation
>> 3. Easy placement of examples (all in one, no need to produce separate CSDs)
>> 4. Readability
>> 5. No need to edit main manual to insert pages.
>>
>> As an example, this is the type of workflow I see would be very handy
>>
>> 1. Open editor of choice.
>> 2. Type the manual page using markdown-like annotations.
>> 3. Add example directly to text.
>> 4. Save it to relevant source folder.
>> 5. Compile the manual.
>>
>> ========================
>> Prof. Victor Lazzarini
>> Maynooth University
>> Ireland
>>
>>> On 30 Sep 2019, at 15:37, Steven Yi <stevenyi@gmail.com> wrote:
>>>
>>> Also an important issue is that a number of tools are built around the
>>> documentation. I know Blue uses a python script to read the
>>> documentation as XML and generate information it uses for syntax
>>> highlighting and presenting of opcode information to the user.  Also,
>>> I depend upon the HTML output organization with opcode entries going
>>> to files with [opcodename].html.  I think CsoundQt and Cabbage may be
>>> in the same boat, perhaps others.
>>>
>>> This is to say that the documentation is not just a format for output
>>> to the print/screen manual, but also a data source too.  I'm all for
>>> transitioning the documentation to a new format as long as we also
>>> keep the data aspect in mind.
>>>
>>> On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>>>> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
>>>> things are essential:
>>>>
>>>> 1. easy to edit and to add reference pages
>>>> 2. easy to render to all formats we need (plus others as a bonus)
>>>>
>>>> I think leading this change is probably a job for whoever takes on as editor.
>>>> ========================
>>>> Prof. Victor Lazzarini
>>>> Maynooth University
>>>> Ireland
>>>>
>>>>> On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
>>>>>
>>>>> I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
>>>>>
>>>>> On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
>>>>> On 30.09.19 11:28, Victor Lazzarini wrote:
>>>>>> Good resolutions. A few comments from me.
>>>>>>
>>>>>> 1. We need a manual editor/maintainer. François has been kindly building the
>>>>>> releases, but I think we do not have anyone leading editorial decisions and
>>>>>> organising the manual. All the things listed there need quite a bit of work and
>>>>>> the reason they have not been done is because no one is taking the editor’s
>>>>>> job. That should be a recognised position, and named at the top of the manual,
>>>>>> e.g.
>>>>>>
>>>>>> Csound Reference Manual
>>>>>> Jane Doe, Editor
>>>>>>
>>>>>> and a recognised publication, possibly with DOI etc. that we can cite.
>>>>> Would it be thinkable to convert the manual to a different format?
>>>>> docbook takes really too long to build and there does not seem to be any
>>>>> way to parallelize it. There is also a lot of manual indexing involved
>>>>> that could be automated (adding an opcode to a specific category, adding
>>>>> it to the global list of opcodes, etc)
>>>>>
>>>>> Csound mailing list
>>>>> Csound@listserv.heanet.ie
>>>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>>>> Send bugs reports to
>>>>>        https://github.com/csound/csound/issues
>>>>> Discussions of bugs and features can be posted here
>>>>> Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>>>>
>>>> Csound mailing list
>>>> Csound@listserv.heanet.ie
>>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>>> Send bugs reports to
>>>>        https://github.com/csound/csound/issues
>>>> Discussions of bugs and features can be posted here
>>> Csound mailing list
>>> Csound@listserv.heanet.ie
>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> Send bugs reports to
>>>        https://github.com/csound/csound/issues
>>> Discussions of bugs and features can be posted here
>>
>> Csound mailing list
>> Csound@listserv.heanet.ie
>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>> Send bugs reports to
>>         https://github.com/csound/csound/issues
>> Discussions of bugs and features can be posted here
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>       https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here


Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Another point is to look for formats/toolchains that are standard and widely used. 

The mistake would be to have a dependency that suddenly is not maintained anymore.

Prof. Victor Lazzarini

Maynooth University

Ireland

On 30 Sep 2019, at 16:13, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:

that's true, I would not want to abandon static html output at all. I think all the frontends would benefit from a modern queryable programmatic format.

Thanks for pointing that out.

A source of inspiration is what the clojure community has been doing with their documentation, 2 frontends at least are using https://clojuredocs-edn.netlify.com/ endpoint for syntax highlighting. And as an alternative a new community driven documentation site https://cljdoc.org/ which is just amazing!

On Mon, 30 Sep 2019 at 16:37, Steven Yi <stevenyi@gmail.com> wrote:

Also an important issue is that a number of tools are built around the
documentation. I know Blue uses a python script to read the
documentation as XML and generate information it uses for syntax
highlighting and presenting of opcode information to the user.  Also,
I depend upon the HTML output organization with opcode entries going
to files with [opcodename].html.  I think CsoundQt and Cabbage may be
in the same boat, perhaps others.

This is to say that the documentation is not just a format for output
to the print/screen manual, but also a data source too.  I'm all for
transitioning the documentation to a new format as long as we also
keep the data aspect in mind.

On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>
> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
> things are essential:
>
> 1. easy to edit and to add reference pages
> 2. easy to render to all formats we need (plus others as a bonus)
>
> I think leading this change is probably a job for whoever takes on as editor.
> ========================
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
> >
> > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
> >
> > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> > On 30.09.19 11:28, Victor Lazzarini wrote:
> > > Good resolutions. A few comments from me.
> > >
> > > 1. We need a manual editor/maintainer. François has been kindly building the
> > > releases, but I think we do not have anyone leading editorial decisions and
> > > organising the manual. All the things listed there need quite a bit of work and
> > > the reason they have not been done is because no one is taking the editor’s
> > > job. That should be a recognised position, and named at the top of the manual,
> > > e.g.
> > >
> > > Csound Reference Manual
> > > Jane Doe, Editor
> > >
> > > and a recognised publication, possibly with DOI etc. that we can cite.
> >
> > Would it be thinkable to convert the manual to a different format?
> > docbook takes really too long to build and there does not seem to be any
> > way to parallelize it. There is also a lot of manual indexing involved
> > that could be automated (adding an opcode to a specific category, adding
> > it to the global list of opcodes, etc)
> >
> > Csound mailing list
> > Csound@listserv.heanet.ie
> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> > Send bugs reports to
> >         https://github.com/csound/csound/issues
> > Discussions of bugs and features can be posted here
> > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Dear Csounders,

 

I would like to help in the revision of the manual and write more nice examples for it. And I think some of the other students of Joachim are going to be interested in doing this, so we’ll discuss this in our class, see who is interested and divide the job…

Making videos and tutorials for the Youtube channel is very important for the new Csounders. And if there is an official Youtube channel, I think it is important that the videos that are being made are outlined in more or less the same form. For example, if it is a video for “How to do FM in Csound”, then there is a brief description of what FM is and how to do it in Csound using different opcodes and some examples for that… But it is important that this is taken in consideration before the videos are being made… I am highly supportive of this and can do some videos myself…

Csound Summer School is a great idea!

And another thing that I noticed is that there are very few female composers that are active in the community and I am willing to take the initiative to encourage female composers to be more included and active and maybe in some of the future Csound conferences (or in the Summer School) we organize a concert for female composers… just an idea…

And thank you everyone for the amazing energy on the conference! It was a pleasure to meet you all!

 

All the best,

Marijana Janevska

On Mon, Sep 30, 2019 at 5:43 PM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:

Another point is to look for formats/toolchains that are standard and widely used. 

The mistake would be to have a dependency that suddenly is not maintained anymore.

Prof. Victor Lazzarini

Maynooth University

Ireland

On 30 Sep 2019, at 16:13, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:

that's true, I would not want to abandon static html output at all. I think all the frontends would benefit from a modern queryable programmatic format.

Thanks for pointing that out.

A source of inspiration is what the clojure community has been doing with their documentation, 2 frontends at least are using https://clojuredocs-edn.netlify.com/ endpoint for syntax highlighting. And as an alternative a new community driven documentation site https://cljdoc.org/ which is just amazing!

On Mon, 30 Sep 2019 at 16:37, Steven Yi <stevenyi@gmail.com> wrote:

Also an important issue is that a number of tools are built around the
documentation. I know Blue uses a python script to read the
documentation as XML and generate information it uses for syntax
highlighting and presenting of opcode information to the user.  Also,
I depend upon the HTML output organization with opcode entries going
to files with [opcodename].html.  I think CsoundQt and Cabbage may be
in the same boat, perhaps others.

This is to say that the documentation is not just a format for output
to the print/screen manual, but also a data source too.  I'm all for
transitioning the documentation to a new format as long as we also
keep the data aspect in mind.

On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>
> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
> things are essential:
>
> 1. easy to edit and to add reference pages
> 2. easy to render to all formats we need (plus others as a bonus)
>
> I think leading this change is probably a job for whoever takes on as editor.
> ========================
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
> >
> > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
> >
> > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> > On 30.09.19 11:28, Victor Lazzarini wrote:
> > > Good resolutions. A few comments from me.
> > >
> > > 1. We need a manual editor/maintainer. François has been kindly building the
> > > releases, but I think we do not have anyone leading editorial decisions and
> > > organising the manual. All the things listed there need quite a bit of work and
> > > the reason they have not been done is because no one is taking the editor’s
> > > job. That should be a recognised position, and named at the top of the manual,
> > > e.g.
> > >
> > > Csound Reference Manual
> > > Jane Doe, Editor
> > >
> > > and a recognised publication, possibly with DOI etc. that we can cite.
> >
> > Would it be thinkable to convert the manual to a different format?
> > docbook takes really too long to build and there does not seem to be any
> > way to parallelize it. There is also a lot of manual indexing involved
> > that could be automated (adding an opcode to a specific category, adding
> > it to the global list of opcodes, etc)
> >
> > Csound mailing list
> > Csound@listserv.heanet.ie
> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> > Send bugs reports to
> >         https://github.com/csound/csound/issues
> > Discussions of bugs and features can be posted here
> > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Thanks Marijana. Please let us know the outcome of your discussions in class. With regards to the few female composers in the community, I think this is a real issue that needs addressing. There were no female presenters giving any talks this year, or in any of the previous conferences from what I can recall. There have never been any keynotes by women, yet there have been female composers featured in many concerts. From the outside in this community looks extremely lobsided. Whatever the next event is, please let us reach out to some female composers and get them to share their experiences with us! 

On Thu, 3 Oct 2019 at 10:53, Marijana Janevska <marijana.janevska90@gmail.com> wrote:

Dear Csounders,

 

I would like to help in the revision of the manual and write more nice examples for it. And I think some of the other students of Joachim are going to be interested in doing this, so we’ll discuss this in our class, see who is interested and divide the job…

Making videos and tutorials for the Youtube channel is very important for the new Csounders. And if there is an official Youtube channel, I think it is important that the videos that are being made are outlined in more or less the same form. For example, if it is a video for “How to do FM in Csound”, then there is a brief description of what FM is and how to do it in Csound using different opcodes and some examples for that… But it is important that this is taken in consideration before the videos are being made… I am highly supportive of this and can do some videos myself…

Csound Summer School is a great idea!

And another thing that I noticed is that there are very few female composers that are active in the community and I am willing to take the initiative to encourage female composers to be more included and active and maybe in some of the future Csound conferences (or in the Summer School) we organize a concert for female composers… just an idea…

And thank you everyone for the amazing energy on the conference! It was a pleasure to meet you all!

 

All the best,

Marijana Janevska

On Mon, Sep 30, 2019 at 5:43 PM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:

Another point is to look for formats/toolchains that are standard and widely used. 

The mistake would be to have a dependency that suddenly is not maintained anymore.

Prof. Victor Lazzarini

Maynooth University

Ireland

On 30 Sep 2019, at 16:13, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:

that's true, I would not want to abandon static html output at all. I think all the frontends would benefit from a modern queryable programmatic format.

Thanks for pointing that out.

A source of inspiration is what the clojure community has been doing with their documentation, 2 frontends at least are using https://clojuredocs-edn.netlify.com/ endpoint for syntax highlighting. And as an alternative a new community driven documentation site https://cljdoc.org/ which is just amazing!

On Mon, 30 Sep 2019 at 16:37, Steven Yi <stevenyi@gmail.com> wrote:

Also an important issue is that a number of tools are built around the
documentation. I know Blue uses a python script to read the
documentation as XML and generate information it uses for syntax
highlighting and presenting of opcode information to the user.  Also,
I depend upon the HTML output organization with opcode entries going
to files with [opcodename].html.  I think CsoundQt and Cabbage may be
in the same boat, perhaps others.

This is to say that the documentation is not just a format for output
to the print/screen manual, but also a data source too.  I'm all for
transitioning the documentation to a new format as long as we also
keep the data aspect in mind.

On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>
> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
> things are essential:
>
> 1. easy to edit and to add reference pages
> 2. easy to render to all formats we need (plus others as a bonus)
>
> I think leading this change is probably a job for whoever takes on as editor.
> ========================
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
> >
> > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
> >
> > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> > On 30.09.19 11:28, Victor Lazzarini wrote:
> > > Good resolutions. A few comments from me.
> > >
> > > 1. We need a manual editor/maintainer. François has been kindly building the
> > > releases, but I think we do not have anyone leading editorial decisions and
> > > organising the manual. All the things listed there need quite a bit of work and
> > > the reason they have not been done is because no one is taking the editor’s
> > > job. That should be a recognised position, and named at the top of the manual,
> > > e.g.
> > >
> > > Csound Reference Manual
> > > Jane Doe, Editor
> > >
> > > and a recognised publication, possibly with DOI etc. that we can cite.
> >
> > Would it be thinkable to convert the manual to a different format?
> > docbook takes really too long to build and there does not seem to be any
> > way to parallelize it. There is also a lot of manual indexing involved
> > that could be automated (adding an opcode to a specific category, adding
> > it to the global list of opcodes, etc)
> >
> > Csound mailing list
> > Csound@listserv.heanet.ie
> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> > Send bugs reports to
> >         https://github.com/csound/csound/issues
> > Discussions of bugs and features can be posted here
> > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Hi Marijana,

Yes please take initiative to make women feel more included. I know you will inspire more women composers if they hear your pieces and get to know you, I was very impressed. Making video tutorials is only a good thing, because there are so few videos out there and so much content to cover. If not from myself, then I hope the rest of the csound community can help whenever you reach out for help or propose ideas.

On Thu, 3 Oct 2019 at 12:44, Rory Walsh <rorywalsh@ear.ie> wrote:

Thanks Marijana. Please let us know the outcome of your discussions in class. With regards to the few female composers in the community, I think this is a real issue that needs addressing. There were no female presenters giving any talks this year, or in any of the previous conferences from what I can recall. There have never been any keynotes by women, yet there have been female composers featured in many concerts. From the outside in this community looks extremely lobsided. Whatever the next event is, please let us reach out to some female composers and get them to share their experiences with us! 

On Thu, 3 Oct 2019 at 10:53, Marijana Janevska <marijana.janevska90@gmail.com> wrote:

Dear Csounders,

 

I would like to help in the revision of the manual and write more nice examples for it. And I think some of the other students of Joachim are going to be interested in doing this, so we’ll discuss this in our class, see who is interested and divide the job…

Making videos and tutorials for the Youtube channel is very important for the new Csounders. And if there is an official Youtube channel, I think it is important that the videos that are being made are outlined in more or less the same form. For example, if it is a video for “How to do FM in Csound”, then there is a brief description of what FM is and how to do it in Csound using different opcodes and some examples for that… But it is important that this is taken in consideration before the videos are being made… I am highly supportive of this and can do some videos myself…

Csound Summer School is a great idea!

And another thing that I noticed is that there are very few female composers that are active in the community and I am willing to take the initiative to encourage female composers to be more included and active and maybe in some of the future Csound conferences (or in the Summer School) we organize a concert for female composers… just an idea…

And thank you everyone for the amazing energy on the conference! It was a pleasure to meet you all!

 

All the best,

Marijana Janevska

On Mon, Sep 30, 2019 at 5:43 PM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:

Another point is to look for formats/toolchains that are standard and widely used. 

The mistake would be to have a dependency that suddenly is not maintained anymore.

Prof. Victor Lazzarini

Maynooth University

Ireland

On 30 Sep 2019, at 16:13, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:

that's true, I would not want to abandon static html output at all. I think all the frontends would benefit from a modern queryable programmatic format.

Thanks for pointing that out.

A source of inspiration is what the clojure community has been doing with their documentation, 2 frontends at least are using https://clojuredocs-edn.netlify.com/ endpoint for syntax highlighting. And as an alternative a new community driven documentation site https://cljdoc.org/ which is just amazing!

On Mon, 30 Sep 2019 at 16:37, Steven Yi <stevenyi@gmail.com> wrote:

Also an important issue is that a number of tools are built around the
documentation. I know Blue uses a python script to read the
documentation as XML and generate information it uses for syntax
highlighting and presenting of opcode information to the user.  Also,
I depend upon the HTML output organization with opcode entries going
to files with [opcodename].html.  I think CsoundQt and Cabbage may be
in the same boat, perhaps others.

This is to say that the documentation is not just a format for output
to the print/screen manual, but also a data source too.  I'm all for
transitioning the documentation to a new format as long as we also
keep the data aspect in mind.

On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>
> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
> things are essential:
>
> 1. easy to edit and to add reference pages
> 2. easy to render to all formats we need (plus others as a bonus)
>
> I think leading this change is probably a job for whoever takes on as editor.
> ========================
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
> >
> > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
> >
> > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> > On 30.09.19 11:28, Victor Lazzarini wrote:
> > > Good resolutions. A few comments from me.
> > >
> > > 1. We need a manual editor/maintainer. François has been kindly building the
> > > releases, but I think we do not have anyone leading editorial decisions and
> > > organising the manual. All the things listed there need quite a bit of work and
> > > the reason they have not been done is because no one is taking the editor’s
> > > job. That should be a recognised position, and named at the top of the manual,
> > > e.g.
> > >
> > > Csound Reference Manual
> > > Jane Doe, Editor
> > >
> > > and a recognised publication, possibly with DOI etc. that we can cite.
> >
> > Would it be thinkable to convert the manual to a different format?
> > docbook takes really too long to build and there does not seem to be any
> > way to parallelize it. There is also a lot of manual indexing involved
> > that could be automated (adding an opcode to a specific category, adding
> > it to the global list of opcodes, etc)
> >
> > Csound mailing list
> > Csound@listserv.heanet.ie
> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> > Send bugs reports to
> >         https://github.com/csound/csound/issues
> > Discussions of bugs and features can be posted here
> > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Dear Csounders,

 

I would like to help in the revision of the manual and write more nice examples for it. And I think some of the other students of Joachim are going to be interested in doing this, so we’ll discuss this in our class, see who is interested and divide the job…

Making videos and tutorials for the Youtube channel is very important for the new Csounders. And if there is an official Youtube channel, I think it is important that the videos that are being made are outlined in more or less the same form. For example, if it is a video for “How to do FM in Csound”, then there is a brief description of what FM is and how to do it in Csound using different opcodes and some examples for that… But it is important that this is taken in consideration before the videos are being made… I am highly supportive of this and can do some videos myself…

Csound Summer School is a great idea!

And another thing that I noticed is that there are very few female composers that are active in the community and I am willing to take the initiative to encourage female composers to be more included and active and maybe in some of the future Csound conferences (or in the Summer School) we organize a concert for female composers… just an idea…

And thank you everyone for the amazing energy on the conference! It was a pleasure to meet you all!

 

All the best,

Marijana Janevska

On Mon, Sep 30, 2019 at 5:43 PM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:

Another point is to look for formats/toolchains that are standard and widely used. 

The mistake would be to have a dependency that suddenly is not maintained anymore.

Prof. Victor Lazzarini

Maynooth University

Ireland

On 30 Sep 2019, at 16:13, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:

that's true, I would not want to abandon static html output at all. I think all the frontends would benefit from a modern queryable programmatic format.

Thanks for pointing that out.

A source of inspiration is what the clojure community has been doing with their documentation, 2 frontends at least are using https://clojuredocs-edn.netlify.com/ endpoint for syntax highlighting. And as an alternative a new community driven documentation site https://cljdoc.org/ which is just amazing!

On Mon, 30 Sep 2019 at 16:37, Steven Yi <stevenyi@gmail.com> wrote:

Also an important issue is that a number of tools are built around the
documentation. I know Blue uses a python script to read the
documentation as XML and generate information it uses for syntax
highlighting and presenting of opcode information to the user.  Also,
I depend upon the HTML output organization with opcode entries going
to files with [opcodename].html.  I think CsoundQt and Cabbage may be
in the same boat, perhaps others.

This is to say that the documentation is not just a format for output
to the print/screen manual, but also a data source too.  I'm all for
transitioning the documentation to a new format as long as we also
keep the data aspect in mind.

On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>
> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
> things are essential:
>
> 1. easy to edit and to add reference pages
> 2. easy to render to all formats we need (plus others as a bonus)
>
> I think leading this change is probably a job for whoever takes on as editor.
> ========================
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
> >
> > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
> >
> > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> > On 30.09.19 11:28, Victor Lazzarini wrote:
> > > Good resolutions. A few comments from me.
> > >
> > > 1. We need a manual editor/maintainer. François has been kindly building the
> > > releases, but I think we do not have anyone leading editorial decisions and
> > > organising the manual. All the things listed there need quite a bit of work and
> > > the reason they have not been done is because no one is taking the editor’s
> > > job. That should be a recognised position, and named at the top of the manual,
> > > e.g.
> > >
> > > Csound Reference Manual
> > > Jane Doe, Editor
> > >
> > > and a recognised publication, possibly with DOI etc. that we can cite.
> >
> > Would it be thinkable to convert the manual to a different format?
> > docbook takes really too long to build and there does not seem to be any
> > way to parallelize it. There is also a lot of manual indexing involved
> > that could be automated (adding an opcode to a specific category, adding
> > it to the global list of opcodes, etc)
> >
> > Csound mailing list
> > Csound@listserv.heanet.ie
> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> > Send bugs reports to
> >         https://github.com/csound/csound/issues
> > Discussions of bugs and features can be posted here
> > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Hi Marijana,

Thanks for the initiative to encourage and support more female Csound users to be active and included in the community. I put Anna Xambó of WoNoMute on CC too and hope you two get in touch with each other. Maybe a German branch of WoNoMuTe (WoGeMuTe?) could be started, or other networking activity to connect these growing initiatives.

Thanks for your inspiring music too!

Oeyvind

tor. 3. okt. 2019 kl. 11:52 skrev Marijana Janevska <marijana.janevska90@gmail.com>:

Dear Csounders,

 

I would like to help in the revision of the manual and write more nice examples for it. And I think some of the other students of Joachim are going to be interested in doing this, so we’ll discuss this in our class, see who is interested and divide the job…

Making videos and tutorials for the Youtube channel is very important for the new Csounders. And if there is an official Youtube channel, I think it is important that the videos that are being made are outlined in more or less the same form. For example, if it is a video for “How to do FM in Csound”, then there is a brief description of what FM is and how to do it in Csound using different opcodes and some examples for that… But it is important that this is taken in consideration before the videos are being made… I am highly supportive of this and can do some videos myself…

Csound Summer School is a great idea!

And another thing that I noticed is that there are very few female composers that are active in the community and I am willing to take the initiative to encourage female composers to be more included and active and maybe in some of the future Csound conferences (or in the Summer School) we organize a concert for female composers… just an idea…

And thank you everyone for the amazing energy on the conference! It was a pleasure to meet you all!

 

All the best,

Marijana Janevska

On Mon, Sep 30, 2019 at 5:43 PM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:

Another point is to look for formats/toolchains that are standard and widely used. 

The mistake would be to have a dependency that suddenly is not maintained anymore.

Prof. Victor Lazzarini

Maynooth University

Ireland

On 30 Sep 2019, at 16:13, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:

that's true, I would not want to abandon static html output at all. I think all the frontends would benefit from a modern queryable programmatic format.

Thanks for pointing that out.

A source of inspiration is what the clojure community has been doing with their documentation, 2 frontends at least are using https://clojuredocs-edn.netlify.com/ endpoint for syntax highlighting. And as an alternative a new community driven documentation site https://cljdoc.org/ which is just amazing!

On Mon, 30 Sep 2019 at 16:37, Steven Yi <stevenyi@gmail.com> wrote:

Also an important issue is that a number of tools are built around the
documentation. I know Blue uses a python script to read the
documentation as XML and generate information it uses for syntax
highlighting and presenting of opcode information to the user.  Also,
I depend upon the HTML output organization with opcode entries going
to files with [opcodename].html.  I think CsoundQt and Cabbage may be
in the same boat, perhaps others.

This is to say that the documentation is not just a format for output
to the print/screen manual, but also a data source too.  I'm all for
transitioning the documentation to a new format as long as we also
keep the data aspect in mind.

On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>
> I think it could be time to move on, but it looks like a big job to move to a different format. I think two
> things are essential:
>
> 1. easy to edit and to add reference pages
> 2. easy to render to all formats we need (plus others as a bonus)
>
> I think leading this change is probably a job for whoever takes on as editor.
> ========================
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
> >
> > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
> >
> > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
> > On 30.09.19 11:28, Victor Lazzarini wrote:
> > > Good resolutions. A few comments from me.
> > >
> > > 1. We need a manual editor/maintainer. François has been kindly building the
> > > releases, but I think we do not have anyone leading editorial decisions and
> > > organising the manual. All the things listed there need quite a bit of work and
> > > the reason they have not been done is because no one is taking the editor’s
> > > job. That should be a recognised position, and named at the top of the manual,
> > > e.g.
> > >
> > > Csound Reference Manual
> > > Jane Doe, Editor
> > >
> > > and a recognised publication, possibly with DOI etc. that we can cite.
> >
> > Would it be thinkable to convert the manual to a different format?
> > docbook takes really too long to build and there does not seem to be any
> > way to parallelize it. There is also a lot of manual indexing involved
> > that could be automated (adding an opcode to a specific category, adding
> > it to the global list of opcodes, etc)
> >
> > Csound mailing list
> > Csound@listserv.heanet.ie
> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> > Send bugs reports to
> >         https://github.com/csound/csound/issues
> > Discussions of bugs and features can be posted here
> > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
>
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>         https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Dear Marijana,

This all sounds fantastic. I particularly like the initiative to help
the diversity of representation in this community. Hopefully everyone,
regardless of identity, will feel encouraged to participate and share
online and in person at future gatherings and conferences.

A video tutorials team collaboration would be great I think.  Any of
these tasks can be onerous for one person, but perhaps a few people
together can make this not too much.  I think a common production on
videos would be nice.  However, I think anyone should feel encouraged
to produce their own videos too, and we can give them visibility on
the csound.com site by having a list of video playlists. (Just
thinking out loud here.)

All best and thanks again for your initiative!

Steven



On Thu, Oct 3, 2019 at 5:52 AM Marijana Janevska
<marijana.janevska90@gmail.com> wrote:
>
> Dear Csounders,
>
>
>
> I would like to help in the revision of the manual and write more nice examples for it. And I think some of the other students of Joachim are going to be interested in doing this, so we’ll discuss this in our class, see who is interested and divide the job…
>
> Making videos and tutorials for the Youtube channel is very important for the new Csounders. And if there is an official Youtube channel, I think it is important that the videos that are being made are outlined in more or less the same form. For example, if it is a video for “How to do FM in Csound”, then there is a brief description of what FM is and how to do it in Csound using different opcodes and some examples for that… But it is important that this is taken in consideration before the videos are being made… I am highly supportive of this and can do some videos myself…
>
> Csound Summer School is a great idea!
>
> And another thing that I noticed is that there are very few female composers that are active in the community and I am willing to take the initiative to encourage female composers to be more included and active and maybe in some of the future Csound conferences (or in the Summer School) we organize a concert for female composers… just an idea…
>
> And thank you everyone for the amazing energy on the conference! It was a pleasure to meet you all!
>
>
>
> All the best,
>
> Marijana Janevska
>
>
> On Mon, Sep 30, 2019 at 5:43 PM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>>
>> Another point is to look for formats/toolchains that are standard and widely used.
>>
>> The mistake would be to have a dependency that suddenly is not maintained anymore.
>>
>> Prof. Victor Lazzarini
>> Maynooth University
>> Ireland
>>
>> On 30 Sep 2019, at 16:13, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
>>
>> that's true, I would not want to abandon static html output at all. I think all the frontends would benefit from a modern queryable programmatic format.
>>
>> Thanks for pointing that out.
>>
>> A source of inspiration is what the clojure community has been doing with their documentation, 2 frontends at least are using https://clojuredocs-edn.netlify.com/ endpoint for syntax highlighting. And as an alternative a new community driven documentation site https://cljdoc.org/ which is just amazing!
>>
>> On Mon, 30 Sep 2019 at 16:37, Steven Yi <stevenyi@gmail.com> wrote:
>>>
>>> Also an important issue is that a number of tools are built around the
>>> documentation. I know Blue uses a python script to read the
>>> documentation as XML and generate information it uses for syntax
>>> highlighting and presenting of opcode information to the user.  Also,
>>> I depend upon the HTML output organization with opcode entries going
>>> to files with [opcodename].html.  I think CsoundQt and Cabbage may be
>>> in the same boat, perhaps others.
>>>
>>> This is to say that the documentation is not just a format for output
>>> to the print/screen manual, but also a data source too.  I'm all for
>>> transitioning the documentation to a new format as long as we also
>>> keep the data aspect in mind.
>>>
>>> On Mon, Sep 30, 2019 at 9:31 AM Victor Lazzarini <Victor.Lazzarini@mu.ie> wrote:
>>> >
>>> > I think it could be time to move on, but it looks like a big job to move to a different format. I think two
>>> > things are essential:
>>> >
>>> > 1. easy to edit and to add reference pages
>>> > 2. easy to render to all formats we need (plus others as a bonus)
>>> >
>>> > I think leading this change is probably a job for whoever takes on as editor.
>>> > ========================
>>> > Prof. Victor Lazzarini
>>> > Maynooth University
>>> > Ireland
>>> >
>>> > > On 30 Sep 2019, at 13:54, Hlöðver Sigurðsson <hlolli@gmail.com> wrote:
>>> > >
>>> > > I discussed it with some people, that it makes sense to go for another format than docbook. Could be json, yaml or even python dictionary. From a more programmating format its easy to render various formats. As well, for front ends to generate syntax highlighting and minidocs. XML is becoming too arcane imo.
>>> > >
>>> > > On Mon, 30 Sep 2019 at 12:17, Eduardo Moguillansky <eduardo.moguillansky@gmail.com> wrote:
>>> > > On 30.09.19 11:28, Victor Lazzarini wrote:
>>> > > > Good resolutions. A few comments from me.
>>> > > >
>>> > > > 1. We need a manual editor/maintainer. François has been kindly building the
>>> > > > releases, but I think we do not have anyone leading editorial decisions and
>>> > > > organising the manual. All the things listed there need quite a bit of work and
>>> > > > the reason they have not been done is because no one is taking the editor’s
>>> > > > job. That should be a recognised position, and named at the top of the manual,
>>> > > > e.g.
>>> > > >
>>> > > > Csound Reference Manual
>>> > > > Jane Doe, Editor
>>> > > >
>>> > > > and a recognised publication, possibly with DOI etc. that we can cite.
>>> > >
>>> > > Would it be thinkable to convert the manual to a different format?
>>> > > docbook takes really too long to build and there does not seem to be any
>>> > > way to parallelize it. There is also a lot of manual indexing involved
>>> > > that could be automated (adding an opcode to a specific category, adding
>>> > > it to the global list of opcodes, etc)
>>> > >
>>> > > Csound mailing list
>>> > > Csound@listserv.heanet.ie
>>> > > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> > > Send bugs reports to
>>> > >         https://github.com/csound/csound/issues
>>> > > Discussions of bugs and features can be posted here
>>> > > Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>>> >
>>> >
>>> > Csound mailing list
>>> > Csound@listserv.heanet.ie
>>> > https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> > Send bugs reports to
>>> >         https://github.com/csound/csound/issues
>>> > Discussions of bugs and features can be posted here
>>>
>>> Csound mailing list
>>> Csound@listserv.heanet.ie
>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> Send bugs reports to
>>>         https://github.com/csound/csound/issues
>>> Discussions of bugs and features can be posted here
>>
>> Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>>
>> Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here
>
> Csound mailing list Csound@listserv.heanet.ie https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND Send bugs reports to https://github.com/csound/csound/issues Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here