[matplotlib-devel] Unifying numpy, scipy, and matplotlib docstring formats
I'd like to help the docstring formats of numpy, scipy. and matplotlib converge on a high-quality standard (hence the cross-posting). However, before that can happen all maintainers from all three packages need to agree on a format. In the interest of speeding things along, I've taken the liberty of extending [1] the docstring format proposed by Travis on January 10th on the scipy-dev mailing list [2]. I also volunteer to convert a non-trivial portion of the numpy, scipy, and matplotlib docstrings. If all goes well on the consensus front, I'll try to coordinate an IRC docstring sprint or two. The notable differences from the format Travis posted is that I have capitalized headers for readability; the other changes are mostly modest, or additions to handle the more demanding requirements of matplotlib docstrings. On the DocstringStandard page I have also put a completely re-done docstring for the 'contour' function from matplotlib. I think it is far more readable than the original [3]. JDH and other matplotlibheads, what do you think? Travis, do you find my additions reasonable? Scipy maintainers, would you consider adopting this format (especially if someone helps with the gruntwork)? Thanks in advance, Keir [1] http://scipy.org/DocstringStandard [2] http://article.gmane.org/gmane.comp.python.scientific.devel/5572 [3] http://matplotlib.sourceforge.net/matplotlib.pylab.html#-contour p.s. This is part of my plan to kick off http://scipy.org/PyLab - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] [PATCH] don't print undefined glyphs in ps backend
> I don't remember why we did it this way originally, or if was you or I > who did it, but if it is correct that the mapping is sometimes many > codes point to one one glyph index, but there each glyph index must > point to a single character code (the latter must be correct, right?) > then reversing it seems to be the right course. But it's been a long > time since I delved into freetype internals ... FreeType 2 documentation states very clearly that character codes are mapped to glyph indices, not the opposite. I think the mapping from glyph indices to character codes is useless, and I've not seen any use case of that in matplotlib. The page http://www.freetype.org/freetype2/docs/tutorial/step1.html says: - "A face object contains one or more tables, called charmaps, that are used to convert character codes to glyph indices." - "To convert a Unicode character code to a font glyph index, we use FT_Get_Char_Index, as in "glyph_index = FT_Get_Char_Index( face, charcode );". This will look the glyph index corresponding to the given charcode in the charmap that is currently selected for the face." The page http://www.freetype.org/freetype2/docs/reference/ft2-base_interface.html says: - "FT_Get_First_Char: This function is used to return the first character code in the current charmap of a given face. It also returns the corresponding glyph index." - "FT_Get_Next_Char: This function is used to return the next character code in the current charmap of a given face following the value 'char_code', as well as the corresponding glyph index." Thanks, -- Nicolas - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] [PATCH] don't print undefined glyphs in ps backend
On 2/14/07, Paul Barrett <[EMAIL PROTECTED]> wrote: > My first reply: > > I suggest that this patch not be applied, since this was the intended > behavior when the font manager was implemented. The standard behavior > for indicating a missing character is to print a square. In addition, > if a space is printed, how will you know when the formatting is > correct or not. The unanticipated space could mean font is missing > that character, or the layout manager has a bug? I agree with that. The character name .notdef exists for that purpose and should be represented by a square or a question mark or something else, depending on the viewing application. Therefore, the character name .notdef should not be ignored or replaced by a space. > and second reply: > > If my memory serves me correctly - or if the implementation has > changed over the past few years - get_charmap() is a wrapper on the > FreeType method. FreeType had no reverse mapping and creating one may > have caused problems later. Matplotlib's method get_charmap is a wrapper around FreeType's functions FT_Get_First_Char and FT_Get_Next_Char. These functions are designed to map character codes to glyph indices, nothing else. But our method get_charmap does the opposite, which seems strange. > I prefer the second alternative. If FreeType now has a reverse > mapping, then by all means create a wrapper for it. If not, then you > will need to take some care that get_rcharmap is reasonably future > proof, so that it does cause maintenance problem later on. To my knowledge, there is no "reverse mapping" in FreeType. There is only one mapping: character code -> glyph index. John wrote: > > I don't remember why we did it this way originally, or if was you or I > > who did it, but if it is correct that the mapping is sometimes many > > codes point to one one glyph index, but there each glyph index must > > point to a single character code (the latter must be correct, right?) > > then reversing it seems to be the right course. But it's been a long > > time since I delved into freetype internals ... 1 character code maps to exactly 1 glyph index. I think the opposite assumpation, i.e. 1 glyph index maps to exactly 1 character code, is incorrect. > I think I did it. At the time the reverse mapping seemed the best > approach, since this ultimately is what the code demanded. (I guess > my memory has failed me!) We also did not have any examples of the > many to one mapping. As you state, this has now changed and the > latter must be correct. This now explains the FreeType implementation. Conclusion: I think we should change the following line in ft2font.cpp from: charmap[Py::Int((int) index)] = Py::Long((long) code); to: charmap[Py::Long((long) code)] = Py::Int((int) index); as proposed by Evgeniy. This will simplify the few lines of code using it in .py files. -- Nicolas - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
[matplotlib-devel] vacation
I'll be away on vacation fro Feb 16th-Feb23rd, and for the most part out of email contact. Hold down the fort for me! JDH - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] [PATCH] don't print undefined glyphs in ps backend
On Thursday 15 February 2007 21:41, Nicolas Grilly wrote: > On 2/14/07, Paul Barrett <[EMAIL PROTECTED]> wrote: > > My first reply: > > > > I suggest that this patch not be applied, since this was the intended > > behavior when the font manager was implemented. The standard behavior > > for indicating a missing character is to print a square. In addition, > > if a space is printed, how will you know when the formatting is > > correct or not. The unanticipated space could mean font is missing > > that character, or the layout manager has a bug? > > I agree with that. The character name .notdef exists for that purpose > and should be represented by a square or a question mark or something > else, depending on the viewing application. Therefore, the character > name .notdef should not be ignored or replaced by a space. > > > and second reply: > > > > If my memory serves me correctly - or if the implementation has > > changed over the past few years - get_charmap() is a wrapper on the > > FreeType method. FreeType had no reverse mapping and creating one may > > have caused problems later. > > Matplotlib's method get_charmap is a wrapper around FreeType's > functions FT_Get_First_Char and FT_Get_Next_Char. These functions are > designed to map character codes to glyph indices, nothing else. But > our method get_charmap does the opposite, which seems strange. > > > I prefer the second alternative. If FreeType now has a reverse > > mapping, then by all means create a wrapper for it. If not, then you > > will need to take some care that get_rcharmap is reasonably future > > proof, so that it does cause maintenance problem later on. > > To my knowledge, there is no "reverse mapping" in FreeType. There is > only one mapping: character code -> glyph index. > > John wrote: > > > I don't remember why we did it this way originally, or if was you or I > > > who did it, but if it is correct that the mapping is sometimes many > > > codes point to one one glyph index, but there each glyph index must > > > point to a single character code (the latter must be correct, right?) > > > then reversing it seems to be the right course. But it's been a long > > > time since I delved into freetype internals ... > > 1 character code maps to exactly 1 glyph index. I think the opposite > assumpation, i.e. 1 glyph index maps to exactly 1 character code, is > incorrect. > > > I think I did it. At the time the reverse mapping seemed the best > > approach, since this ultimately is what the code demanded. (I guess > > my memory has failed me!) We also did not have any examples of the > > many to one mapping. As you state, this has now changed and the > > latter must be correct. This now explains the FreeType implementation. > > Conclusion: > I think we should change the following line in ft2font.cpp from: > charmap[Py::Int((int) index)] = Py::Long((long) code); > to: > charmap[Py::Long((long) code)] = Py::Int((int) index); > as proposed by Evgeniy. > > This will simplify the few lines of code using it in .py files. I agree with what you said, I've also never heard of glyph index -> character code mapping. I've checked all ps and png outputs from examples/, everything seems ok. - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] [Numpy-discussion] Unifying numpy, scipy, and matplotlib docstring formats
On 2/15/07, Robert Kern <[EMAIL PROTECTED]> wrote: > On 2/15/07, Keir Mierle <[EMAIL PROTECTED]> wrote: > > On the DocstringStandard page I have also put a completely re-done docstring > > for the 'contour' function from matplotlib. I think it is far more readable > > than the original [3]. JDH and other matplotlibheads, what do you think? > > Travis, do you find my additions reasonable? Scipy maintainers, would you > > consider adopting this format (especially if someone helps with the > > gruntwork)? > > It looks like you took the initial proposal rather than the result of > that discussion. Please see the document that we came up with: > > http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_DOCUMENT.txt Ah, I apologize for not checking the dates; I thought the HOWTO_DOCUMENT.txt was the older proposal. Nevertheless, I think the issues raised in my proposed version are significant enough to warrent further discussion; especially for the more demanding needs of matplotlib. I would like to re-open this discussion to be sure there is consensus among the numpy, scipy, and matplotlib folk before I invest signifcant time into massaging the docstrings into the right form. I am clearly biased as I invested time and thought into the proposed docstring format I posted [1], but nevertheless I do not like the style listed in the HOWTO_DOCUMENT.txt. The different sections have different styles of headings, i.e. the difference style for :Pamaraters: and Examples, which is not good for readability. Furthermore, it does not specify enough formatting, for e.g. keyword arguments with defaults. For specifics, here are my issues with the current HOWTO: * Non-capitalized headers Capitalized headers are far more visually obvious when viewed on a text terminal (i.e. via function? in IPython) * Two different header styles The distinction between :Parameters: and Examples seems unnecessary; if this is necessary for reST, could a preprocessing step not fix this? The inconsistency appears unprofessional when viewed in a terminal. * No suggestions on how to handle functions which have multiple invocations, i.e. multiple function signatures. I have a proposal for this in [1]. * Parameters / Returns instead of INPUTS / OUTPUTS. This is no doubt a preference, but nevertheless I vastly prefer having INPUTS / OUTPUTS instead of Parameters / Returns. I understand that the parameter/return form is more common for Python, so I realize this is contentious. Nevertheless, inputs / outputs has the clear advantage of being informative to someone who is just starting programming and may not realize the meanings of parameters / returns; but input/output is absolutely clear even to the non-programmer. If it comes down to me writing a parser for my proposed format, I will do that. Keir [1] http://scipy.org/DocstringStandard - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
