Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> > See the attached screenshots, for an idea of how this will work.
>
> Looks good!
>

Great, changes implemented and wiki updated! I have removed the
original tilde method.


-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

> I just realized that this would cause a problem with nested lists.
> A solution here is to indent multi-paragraph lists to 4 spaces in
> the docs itself, so that docwriter is freed from the responsibility
> of keeping track of the spaces.

Yes.

> See the attached screenshots, for an idea of how this will work.

Looks good!


Werner

___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> Hmm.  What about making DocPara strip leading and trailing spaces
> *except* for the first leading space in a paragraph?


This seems reasonable. This will be implemented as follows:

* DocPara will have a new property 'indent' which will store the
  indentation of the first line of the paragraph.

* The previous paragraph's indent value will be stored as the 'margin'
  in the caller (DocField).

* 'margin' will be sent while creating DocPara for the next paragraph.

* DocPara will compare this value (previous para's indent) with the
  current indentation. If indent > margin + 2, it will add 4 spaces
  to the first line (see below for why I'm adding 4 spaces).


>   We can enforce
> the assumption that the indentation of a paragraph is determined by
> the number of spaces starting the first line.  If we do that, the
> markdown parser sees the correct indentation.  Am I missing something?
>

Have a look at https://daringfireball.net/projects/markdown/syntax#list
Continuing paragraphs in lists require at least 4-space indentation.

I found an example in 'ftdriver.h
'.
Changing the '1)' to '1.' and indenting the
2nd paragraph still won't work directly with markdown because there will
be only 3 spaces.

Therefore for convenience, I'm keeping the required indentation at 3
spaces, and adding 4 wherever there are 3 or more.

Also, the 3 space minimum indent is because URLs are indented with
2 spaces currently, and I don't want to touch them in the output.

Does this seem to be OK?


-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

>> * I'm not happy with
>>
>> To continue a list over multiple paragraphs, start the paragraphs
>> with a tilde (~) character.
>>
>>   I would rather prefer that a continuation is indented as before.
> 
> The problem with this is, DocPara objects strip leading and trailing
> spaces in the string before storing the words in an array.  Doing
> this will involve analysis of the lines before indentation data is
> removed, and creating another object to store lists.  This is not
> good, because we're essentially doing work that the markdown parser
> is supposed to do.

Hmm.  What about making DocPara strip leading and trailing spaces
*except* for the first leading space in a paragraph?  We can enforce
the assumption that the indentation of a paragraph is determined by
the number of spaces starting the first line.  If we do that, the
markdown parser sees the correct indentation.  Am I missing something?

>> * Shall we mention that we prefer two spaces after a full stop
>>   ending a sentence?  Ditto for details on uppercasing in section
>>   titles (US style, for example `This and That'), how to cite a C
>>   function (without trailing parentheses), etc., etc.
> 
> You know a lot more about these small details, and I think these
> should be added to make the file a nice guide to always refer to.  I
> have added you as a collaborator, please add the necessary
> information!

OK.


Werner

___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> Very nice, thanks!
>

:-)

Some issues.
>
> * s/comfig/config/.


Oops, fixed!


> * I'm not happy with
>
> To continue a list over multiple paragraphs, start the paragraphs
> with a tilde (~) character.
>
>   I would rather prefer that a continuation is indented as before.
>   Example:
>
> 1. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
>Aliquam hendrerit mi posuere lectus.  Vestibulum enim wisi,
>viverra nec, fringilla in, laoreet vitae, risus.
>
>Donec sit amet nisl.  Aliquam semper ipsum sit amet velit.
>Suspendisse id sem consectetuer libero luctus adipiscing.
>
>   [IIRC, Pandoc supports this style.]  Is this possible?  What do you
>   think?
>

The problem with this is, DocPara objects strip leading and trailing
spaces in the string before storing the words in an array. Doing this will
involve analysis of the lines before indentation data is removed, and
creating another object to store lists. This is not good, because we're
essentially doing work that the markdown parser is supposed to do.

This may actually require a complete restructuring of the docs making
all content WYSIWYG, and ensuring all indentation is exactly how we
want it to be in the markdown output.

Or do you think there's another way?


> * Shall we mention that we prefer two spaces after a full stop ending
>   a sentence?  Ditto for details on uppercasing in section titles (US
>   style, for example `This and That'), how to cite a C function
>   (without trailing parentheses), etc., etc.
>

You know a lot more about these small details, and I think these should
be added to make the file a nice guide to always refer to. I have added
you as a collaborator, please add the necessary information!


-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

> I have written a draft for this document, available at
> 
> https://github.com/nikramakrishnan/freetype-docs/wiki/Documentation-Guidelines-for-The-FreeType-Project

Very nice, thanks!

Some issues.

* s/comfig/config/.

* I'm not happy with

To continue a list over multiple paragraphs, start the paragraphs
with a tilde (~) character.

  I would rather prefer that a continuation is indented as before.
  Example:

1. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
   Aliquam hendrerit mi posuere lectus.  Vestibulum enim wisi,
   viverra nec, fringilla in, laoreet vitae, risus.

   Donec sit amet nisl.  Aliquam semper ipsum sit amet velit.
   Suspendisse id sem consectetuer libero luctus adipiscing.

  [IIRC, Pandoc supports this style.]  Is this possible?  What do you
  think?

* Shall we mention that we prefer two spaces after a full stop ending
  a sentence?  Ditto for details on uppercasing in section titles (US
  style, for example `This and That'), how to cite a C function
  (without trailing parentheses), etc., etc.


Werner
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> > Because we will now switch to markdown, we may have to be careful
>> > with the usage of asterisks.  They are used to begin points in
>> > unordered lists and wrap italics text.
>>
>> OK.  This is something to be added to a forthcoming
>> `docs/DOCUMENTATION' file.  I invite you to write this while doing the
>> conversion process :-)
>
>
> Sure! I will write this after I fix minor issues and get docwriter working
> on the FreeType repository tree :-)
>

I have written a draft for this document, available at


https://github.com/nikramakrishnan/freetype-docs/wiki/Documentation-Guidelines-for-The-FreeType-Project

This covers most details from the structure of the docs, to guidelines
on writing them in Markdown. I feel that reading this should be enough
for most developers to understand the documentation process.

Please have a look at it, and let me know if I missed something, and
suggest changes and additions!

-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> Indeed.  Essentially, everything that can be used within C code should
> be tagged with `...`, for example `FT_Glyph`, `FT_GLYPH_H`, etc.
>
> Maybe it makes sense to convert everything starting with `FT_...' to
> `...`?
>

These cases are covered by the regex I added, so stuff with underscores,
arrow operators, and such will be converted to `...` by markify.


> > Because we will now switch to markdown, we may have to be careful
> > with the usage of asterisks.  They are used to begin points in
> > unordered lists and wrap italics text.
>
> OK.  This is something to be added to a forthcoming
> `docs/DOCUMENTATION' file.  I invite you to write this while doing the
> conversion process :-)


Sure! I will write this after I fix minor issues and get docwriter working
on the FreeType repository tree :-)


-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

 
> OK, I came up with 2 regex expressions to try and find inline code
> sequences, and was able to replace 394 `...' quotes to `...`. All
> other quotes will be converted to '...' (these changes were done in
> markify.py).
> 
> However, this is *not* fool-proof, and many variable names would
> have been left out (stuff like 'face', 'source'...)

Indeed.  Essentially, everything that can be used within C code should
be tagged with `...`, for example `FT_Glyph`, `FT_GLYPH_H`, etc.

Maybe it makes sense to convert everything starting with `FT_...' to
`...`?

> Because we will now switch to markdown, we may have to be careful
> with the usage of asterisks.  They are used to begin points in
> unordered lists and wrap italics text.

OK.  This is something to be added to a forthcoming
`docs/DOCUMENTATION' file.  I invite you to write this while doing the
conversion process :-)


Werner
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> Well, `...' should be eventually resolved into `...` and '...'.
>

OK, I came up with 2 regex expressions to try and find inline code
sequences,
and was able to replace 394 `...' quotes to `...`. All other quotes will be
converted to '...' (these changes were done in markify.py).

However, this is *not* fool-proof, and many variable names would have been
left out (stuff like 'face', 'source'...)

(Regex available at
https://github.com/nikramakrishnan/freetype-docs/blob/markdown/markdown_utils.py#L96
,
if anyone is interested).

The changes have been pushed to the preview site.


> I prefer `lsquo' and `rsquo'.
>

OK, I have retained this.

BTW, the problem with the note section in
https://nikramakrishnan.github.io/freetype-site/ft2-glyph_management/#ft_get_glyph
is now fixed because those are now inline code blocks :-)
I'm not sure if there are more of these, but eventually we have to figure
out a way for this to not happen.

Because we will now switch to markdown, we may have to be careful with
the usage of asterisks. They are used to begin points in unordered lists and
wrap italics text.

Asterisks, although should be used directly in inline code blocks (`...`),
should always be escaped (\*) in normal text.

-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

>> Do you mean in the input or in the output?  Right now, `...' in the
>> input has two purposes.
>>
>> (1) It is used as a poor-man's substitute for inline code snippets
>> – the thing Nikhil is talking.
>>
>> (2) It is *really* used for quotations, i.e., `foo' should be
>> converted to ‘foo’.  Note that I prefer ‘foo’ over “foo”, since
>> it is less intrusive to my eyes.
>>

>> This should be disentangled.  However, I don't want to throw away
>> (2) completely.
> 
> Should I look at only changing inline code blocks, or all quotes (in
> input), then?

Well, `...' should be eventually resolved into `...` and '...'.

> Also, in the output, should we retain  and  (‘... ’)
> or should I change those to just single quotes ('..')?

I prefer `lsquo' and `rsquo'.

>> While the majority of `...' is case (1), we have a lot of (2) also.
>> In other words, a fully automated conversion is not possible IMHO.
> 
> It seems like there are 981 instances of quoted text in the docs.  I
> will try to come up with a method to automate this, if possible.
> 
> We can always do a manual cleanup later.

OK.


Werner
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> Do you mean in the input or in the output?  Right now, `...' in the
> input has two purposes.
>
> (1) It is used as a poor-man's substitute for inline code snippets –
> the thing Nikhil is talking.
>
> (2) It is *really* used for quotations, i.e., `foo' should be
> converted to ‘foo’.  Note that I prefer ‘foo’ over “foo”, since it
> is less intrusive to my eyes.
>
> This should be disentangled.  However, I don't want to throw away (2)
> completely.
>

Should I look at only changing inline code blocks, or all quotes (in input),
then?

If you want to retain (2) in the input, that will not be a problem because
we can change it in the output. Further, using 'foo' directly in input
should
also not cause any problems.

Also, in the output, should we retain  and  (‘... ’ ) or
should
I change those to just single quotes ('..')?

> Do we have to change the quote style or your scripts can do it?
>
> While the majority of `...' is case (1), we have a lot of (2) also.
> In other words, a fully automated conversion is not possible IMHO.
>

It seems like there are 981 instances of quoted text in the docs.
I will try to come up with a method to automate this, if possible.

We can always do a manual cleanup later.


> BTW, there is a buglet in the conversion script: Have a look at the
> `note' section of
>
>
> https://nikramakrishnan.github.io/freetype-site/ft2-glyph_management/#ft_get_glyph
>
> The current code in the header file starts with
>
>   Because `*aglyph->advance.x' and '*aglyph->advance.y' are 16.16 ...
>
> Note how the stuff between the two `*' gets incorrectly converted to
> italics in the HTML output.
>

Will fix this, thanks.


-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

>>> I do not like `quoted' text.

Do you mean in the input or in the output?  Right now, `...' in the
input has two purposes.

(1) It is used as a poor-man's substitute for inline code snippets –
the thing Nikhil is talking.

(2) It is *really* used for quotations, i.e., `foo' should be
converted to ‘foo’.  Note that I prefer ‘foo’ over “foo”, since it
is less intrusive to my eyes.

This should be disentangled.  However, I don't want to throw away (2)
completely.

>> I do have a suggestion - Changing variable names and inline code
>> snippets to `foobar` instead of `foobar'.  Markdown will add an
>> inline code block around the text (see attached image).
> 
> Yes, I would prefer this.

Me too.

> There was a reason to use different quotes, which I do not remember.

See (2).  `foo' is good old TeX tradition for quotation input.  It's
OK with me to change the `foo' style to 'foo' for (2) in the source
code, as used by markdown.

> Do we have to change the quote style or your scripts can do it?

While the majority of `...' is case (1), we have a lot of (2) also.
In other words, a fully automated conversion is not possible IMHO.

BTW, there is a buglet in the conversion script: Have a look at the
`note' section of

  
https://nikramakrishnan.github.io/freetype-site/ft2-glyph_management/#ft_get_glyph

The current code in the header file starts with

  Because `*aglyph->advance.x' and '*aglyph->advance.y' are 16.16 ...

Note how the stuff between the two `*' gets incorrectly converted to
italics in the HTML output.


Werner
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Alexei Podtelezhnikov]

>> I do not like `quoted' text.

> I do have a suggestion - Changing variable names and inline code snippets
> to `foobar` instead of `foobar'. Markdown will add an inline code block
> around the text (see attached image).

Yes, I would prefer this. There was a reason to use different quotes,
which I do not remember. Do we have to change the quote style or your
scripts can do it?

Thanks!
Alexei

___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> It is nice that most ordered and unordered lists are picked up. Is it
> described somewhere what is recognized as a list?


For now any list style supported by markdown should work except in
field tables (there is a problem with ordered lists right now, but I am
working to fix this). You can expect any format given in this
handy cheatsheet to work:
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#lists


> I do not like
> `quoted' text. Can we use italics instead of quotes?
>

This depends on how we want to handle quoted text. There is already a
format for italics (underscore), and things like variable names would
look weird in italics.
I do have a suggestion - Changing variable names and inline code snippets
to `foobar` instead of `foobar'. Markdown will add an inline code block
around the text (see attached image).

Any thoughts?

-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

>> * In the `fields' subsection of each element, please reduce the
>>   space between the elements.  In most cases, the descriptions are
>>   only a single line, and (at least with my Chrome browser) this
>>   takes too much vertical space IMHO, see attached image.
> 
> I have reduced the space. Please check!

Better, thanks!


Werner

___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Nikhil Ramakrishnan]

> Right now I've noticed only two issues.
>
> * Looking at
>
> https://nikramakrishnan.github.io/freetype-site/ft2-toc/
>
>   I wonder why the `Docs' link in
>
> Docs » Table of Contents
>
>   points to the index.  Is this intentional?  I assume this is a
>   temporary decision, since later on we mount the whole reference into
>   the FreeType tree so that `Docs' links to
>
> https://www.freetype.org/freetype2/docs/documentation.html
>
>   or something similar, right?
>

This is temporary. I wanted a valid internal link for now, and I will
point this to the documentation link later.


> * In the `fields' subsection of each element, please reduce the space
>   between the elements.  In most cases, the descriptions are only a
>   single line, and (at least with my Chrome browser) this takes too
>   much vertical space IMHO, see attached image.
>

I have reduced the space. Please check!


-- 
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Alexei Podtelezhnikov]

On Tue, Jun 12, 2018 at 8:26 AM, Nikhil Ramakrishnan
 wrote:
> * The complete API documentation site is now available on
> https://nikramakrishnan.github.io/freetype-site/ft2-toc/
> This was generated using docwriter with the header files
> updated to commit b18f5e7c62c0aa6f8d17cbb9a8fe687ed402569a.

This looks really nice. I can see all my errors in
https://nikramakrishnan.github.io/freetype-site/ft2-lcd_rendering/,
which I actually want to move from Support API to Controlling FreeType
Modules.

It is nice that most ordered and unordered lists are picked up. Is it
described somewhere what is recognized as a list? I do not like
`quoted' text. Can we use italics instead of quotes?

Thanks,
Alexei

___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] GSoC Status update and complete API reference website

[Werner LEMBERG]

Hello Nikhil!


> * Also, docwriter
>   (https://github.com/nikramakrishnan/freetype-docwriter) can now
>   output Markdown, and I am in the process of writing code to
>   automatically generate the `yml' configuration file required by
>   MkDocs.

Great!  Will check that within the next few days.

> Please also let me know of any problems you notice with the
> website, and any other comments.

Right now I've noticed only two issues.

* Looking at

https://nikramakrishnan.github.io/freetype-site/ft2-toc/

  I wonder why the `Docs' link in

Docs » Table of Contents

  points to the index.  Is this intentional?  I assume this is a
  temporary decision, since later on we mount the whole reference into
  the FreeType tree so that `Docs' links to

https://www.freetype.org/freetype2/docs/documentation.html

  or something similar, right?

* In the `fields' subsection of each element, please reduce the space
  between the elements.  In most cases, the descriptions are only a
  single line, and (at least with my Chrome browser) this takes too
  much vertical space IMHO, see attached image.


Werner
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel