but in general, I think we can switch to this version and hide the old page and start using and improving it. On Fri, Feb 2, 2018 at 10:26 PM, Stanislav Sinyagin <ssinyagin@gmail.com> wrote:

wow, excellent work, and I like the formatting better than mine.

Next step, we need to find a way to index them. At the moment (I tried) it's impossible to make links to individual variables. This needs help from Confluence experts.

On Fri, Feb 2, 2018 at 10:12 PM, Ryan Harris <ryharris@airmail.cc> wrote:

...

Hi list,

I've mostly completed "normalizing" the channel variables section.

On this page: https://freeswitch.org/confluence/pages/viewpage.action?pageId=7766277

DTMF Variables and all pages below show the new catalog.

If there is _anything_ you think needs to be tweaked, please let me know. Everything can be changed with relative ease: page ordering, variable ordering, variable groups, formatting, datatypes, etc.

Here are some things to look for:

- check for correct data types -- we default to string when it's ambiguous/don't know

- check for deprecated variables - I can mark them as such

- check for variables not marked as readonly - I can mark them as such

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

I thought more of a global way to reference variables from other pages. Also a global index page with just names wouldn't be too bad. On Feb 2, 2018 23:21, "Bote Man" <bote_radio@botecomm.com> wrote:

High praise from Stan! He does good work, too.

You can use an aspect of Confluence Table of Contents to form links within the page, especially since they make it so insanely difficult to create a simple anchor within a page.

The way the 'FS ToC' macro that I created works is by only including the higher level heading tags, I think h1, h2, possibly h3. I can't recall off-hand and I can't check right now.

You can copy an individual link to the term of interest from the ToC and paste that elsewhere. It's cumbersome, but it's less cumbersome than the way Confluence wants you to do it. Have a look at https://freeswitch.org/ confluence/display/FREESWITCH/Conference+Related

I see Confluence led you down the garden path of inserting Sections :-) I learned the hard way that they are a royal pain to manipulate, especially when a section is the first element on a page: you aint inserting ANYTHING before it.

See if that ToC idea helps you. Lots of good work there, thank you.

Bote

-----Original Message----- From: Freeswitch-docs [mailto:freeswitch-docs-bounces@lists.freeswitch.org] On Behalf Of Stanislav Sinyagin Sent: Friday, 02 February, 2018 16:27 To: FreeSWITCH Docs Team <freeswitch-docs@lists.freeswitch.org> Subject: Re: [Freeswitch-docs] Request for comment on new channel variable catalog

wow, excellent work, and I like the formatting better than mine.

Next step, we need to find a way to index them. At the moment (I tried) it's impossible to make links to individual variables. This needs help from Confluence experts.

On Fri, Feb 2, 2018 at 10:12 PM, Ryan Harris <ryharris@airmail.cc> wrote:

...

Hi list,

I've mostly completed "normalizing" the channel variables section.

On this page: https://freeswitch.org/confluence/pages/viewpage.action?pageId=7766277

DTMF Variables and all pages below show the new catalog.

If there is _anything_ you think needs to be tweaked, please let me know. Everything can be changed with relative ease: page ordering, variable ordering, variable groups, formatting, datatypes, etc.

Here are some things to look for:

- check for correct data types -- we default to string when it's ambiguous/don't know

- check for deprecated variables - I can mark them as such

- check for variables not marked as readonly - I can mark them as such

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

if there's no objection, let's make these new pages productive, and hide the old one. On Fri, Feb 2, 2018 at 11:42 PM, Bote Man <bote_radio@botecomm.com> wrote:

Well, if there is a way to do that it would be either a LOT of manual work or a script that somehow magically knows which terms to form into links suitable for Confluence.

Even if such a list were generated from the source code or Doxygen(?) we would still need some way to form the links. I have no good ideas for that. Documentation is largely a manual endeavor, even in the tech field.

Bote

From: Stanislav Sinyagin [mailto:ssinyagin@gmail.com] Sent: Friday, 02 February, 2018 17:23 To: Bote Man <bote_radio@botecomm.com>; FreeSWITCH Docs Team <freeswitch-docs@lists.freeswitch.org>

Subject: Re: [Freeswitch-docs] Request for comment on new channel variable catalog

I thought more of a global way to reference variables from other pages. Also a global index page with just names wouldn't be too bad.

On Feb 2, 2018 23:21, "Bote Man" <bote_radio@botecomm.com> wrote:

High praise from Stan! He does good work, too.

You can use an aspect of Confluence Table of Contents to form links within the page, especially since they make it so insanely difficult to create a simple anchor within a page.

The way the 'FS ToC' macro that I created works is by only including the higher level heading tags, I think h1, h2, possibly h3. I can't recall off-hand and I can't check right now.

You can copy an individual link to the term of interest from the ToC and paste that elsewhere. It's cumbersome, but it's less cumbersome than the way Confluence wants you to do it. Have a look at https://freeswitch.org/confluence/display/FREESWITCH/Conference+Related

I see Confluence led you down the garden path of inserting Sections :-) I learned the hard way that they are a royal pain to manipulate, especially when a section is the first element on a page: you aint inserting ANYTHING before it.

See if that ToC idea helps you. Lots of good work there, thank you.

Bote

-----Original Message----- From: Freeswitch-docs [mailto:freeswitch-docs-bounces@lists.freeswitch.org] On Behalf Of Stanislav Sinyagin Sent: Friday, 02 February, 2018 16:27 To: FreeSWITCH Docs Team <freeswitch-docs@lists.freeswitch.org> Subject: Re: [Freeswitch-docs] Request for comment on new channel variable catalog

wow, excellent work, and I like the formatting better than mine.

Next step, we need to find a way to index them. At the moment (I tried) it's impossible to make links to individual variables. This needs help from Confluence experts.

On Fri, Feb 2, 2018 at 10:12 PM, Ryan Harris <ryharris@airmail.cc> wrote:

...

Hi list,

I've mostly completed "normalizing" the channel variables section.

On this page: https://freeswitch.org/confluence/pages/viewpage.action?pageId=7766277

DTMF Variables and all pages below show the new catalog.

If there is _anything_ you think needs to be tweaked, please let me know. Everything can be changed with relative ease: page ordering, variable ordering, variable groups, formatting, datatypes, etc.

Here are some things to look for:

- check for correct data types -- we default to string when it's ambiguous/don't know

- check for deprecated variables - I can mark them as such

- check for variables not marked as readonly - I can mark them as such

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

On 02/02/2018 06:08 PM, Ítalo Rossi wrote:

Use the default fs toc macro, I think the way it create the sections like 1 1.1 1.2 looks better.

And if you use h1 the variable get anchor links automatically in the toc, easy to reference them. Ah, I think I know what's causing this. To clarify - I am using the default FS TOC, just not including the about part if there was no about section. I've corrected this and all of the pages should have the TOC now. Is the H1 absolutely necessary? They're a little too big to me

On 02/02/2018 07:21 PM, Bote Man wrote:

I gave up worrying about styling in Confluence because it seems to be a blunt tool. I used to get so annoyed at the CSS religionists back in the day because they'd want pixel-perfect design; I don't think Confluence is up to that task.

Style is the afterthought. The focus should be on cohesiveness. We can make small tweaks later to make the design better.

Having said that, I've never been too happy with the look of Confluence, so maybe we can mess with a style sheet in a test instance and apply the good results to the production instance? IDK.

It's growing on me... somewhat. The big problem right now is that the old wiki's styles are messing with the way things look. It causes fatigue because the flow is off.

But the answer is of course modify the style sheet. The trick on the old wiki was just to use h2 because it was smaller, but html has semantic purposes beyond style: screen readers for the blind, for one.

HTML semantics is actually why I chose H2 - you're technically only supposed to have one H1 on the whole page. :\ I hope it reads okay in a screen reader. Part of the motivation behind the Django app is to be able to address situations where we need the documentation in a different format. Atlassian publishes their CSS documentation here (it's how I made the datatype badges): https://docs.atlassian.com/aui/5.8.29/ They have a dedicated CSS class for adding context for screen readers!

So we can't break the pages to make them look differently, instead use the style to get the desired presentation. That's my rant.

Yes - I'm trying to create minimal, correct HTML.

Agreed! There are enough duplications so let's not confuse people. If the new one is incomplete, then that is simply the nature of a wiki. Bote -----Original Message----- From: Stanislav Sinyagin [mailto:ssinyagin@gmail.com] Sent: Friday, 02 February, 2018 17:47 To: Bote Man <bote_radio@botecomm.com>; FreeSWITCH Docs Team <freeswitch-docs@lists.freeswitch.org> Subject: Re: [Freeswitch-docs] Request for comment on new channel variable catalog if there's no objection, let's make these new pages productive, and hide the old one. On Fri, Feb 2, 2018 at 11:42 PM, Bote Man <bote_radio@botecomm.com> wrote:

Well, if there is a way to do that it would be either a LOT of manual work or a script that somehow magically knows which terms to form into links suitable for Confluence.

Even if such a list were generated from the source code or Doxygen(?) we would still need some way to form the links. I have no good ideas for that. Documentation is largely a manual endeavor, even in the tech field.

Bote

From: Stanislav Sinyagin [mailto:ssinyagin@gmail.com] Sent: Friday, 02 February, 2018 17:23 To: Bote Man <bote_radio@botecomm.com>; FreeSWITCH Docs Team <freeswitch-docs@lists.freeswitch.org>

Subject: Re: [Freeswitch-docs] Request for comment on new channel variable catalog

I thought more of a global way to reference variables from other pages. Also a global index page with just names wouldn't be too bad.

On Feb 2, 2018 23:21, "Bote Man" <bote_radio@botecomm.com> wrote:

High praise from Stan! He does good work, too.

You can use an aspect of Confluence Table of Contents to form links within the page, especially since they make it so insanely difficult to create a simple anchor within a page.

The way the 'FS ToC' macro that I created works is by only including the higher level heading tags, I think h1, h2, possibly h3. I can't recall off-hand and I can't check right now.

You can copy an individual link to the term of interest from the ToC and paste that elsewhere. It's cumbersome, but it's less cumbersome than the way Confluence wants you to do it. Have a look at https://freeswitch.org/confluence/display/FREESWITCH/Conference+Relate d

I see Confluence led you down the garden path of inserting Sections :-) I learned the hard way that they are a royal pain to manipulate, especially when a section is the first element on a page: you aint inserting ANYTHING before it.

See if that ToC idea helps you. Lots of good work there, thank you.

Bote

-----Original Message----- From: Freeswitch-docs [mailto:freeswitch-docs-bounces@lists.freeswitch.org] On Behalf Of Stanislav Sinyagin Sent: Friday, 02 February, 2018 16:27 To: FreeSWITCH Docs Team <freeswitch-docs@lists.freeswitch.org> Subject: Re: [Freeswitch-docs] Request for comment on new channel variable catalog

wow, excellent work, and I like the formatting better than mine.

Next step, we need to find a way to index them. At the moment (I tried) it's impossible to make links to individual variables. This needs help from Confluence experts.

On Fri, Feb 2, 2018 at 10:12 PM, Ryan Harris <ryharris@airmail.cc> wrote:

...

Hi list,

I've mostly completed "normalizing" the channel variables section.

On this page: https://freeswitch.org/confluence/pages/viewpage.action?pageId=776627 7

DTMF Variables and all pages below show the new catalog.

If there is _anything_ you think needs to be tweaked, please let me know. Everything can be changed with relative ease: page ordering, variable ordering, variable groups, formatting, datatypes, etc.

Here are some things to look for:

- check for correct data types -- we default to string when it's ambiguous/don't know

- check for deprecated variables - I can mark them as such

- check for variables not marked as readonly - I can mark them as such

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs

_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs