Inclusivity Issues for new contributors

Inclusivity Issues for new contributors

[Aseem Prashar]

[-- Attachment #1.1: Type: text/plain, Size: 1774 bytes --]

Hi everyone!

Oregon State University's Free/Open Source Software class has us evaluate 
real-world open-source projects for inclusivity using a cognitive 
walk-through technique.
I am opening this discussion thread to facilitate conversation on 
inclusivity within the Pandoc project. 

*Issue 1:* Our cognitive walk-through found that contributing to Pandoc 
page (https://github.com/jgm/pandoc/blob/master/CONTRIBUTING.md) doesn’t 
give enough information
on how to set up the environment and start contributing to people who are 
new to open source to encourage them to contribute to this project.

*Issue 2:* The documentation should also provide more instructions on 
setting up the test environment as most people contributing to open source 
for the first time will not be familiar with
the testing methods used. The documentation on what kind of test is done 
and how to test new features should also be included.

*Issue 3: *This tool is mainly for front end developers, but it has been 
implemented as a command line program, making a GUI for the tool will make 
using this tool easier and faster.

Thank you for reading, looking forward to your responses.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/7231afe1-fd0a-4e7d-93ce-fadb9030a244%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 2324 bytes --]

Re: Inclusivity Issues for new contributors

[Lukas Atkinson]

[-- Attachment #1: Type: text/plain, Size: 4012 bytes --]

It's so cool that you have an Open Source class! There also was a similar
review from you class here
<https://groups.google.com/d/msg/pandoc-discuss/SCNaNRT7484/4exwbELFAAAJ>.

On issue 1: I think the documentation clearly covers the Pandoc-specific
parts. It cannot be a guide that starts from zero. However, a short mention
of what cabal and stack are might be useful for people new to Haskell.

On issue 2: the documentation shows how to run the tests – but not how to
create them. I think a short example that mentions "pandoc -t native" would
already be helpful (this was not obvious to me when I tried hacking on
internals).

On issue 3: pandoc is many things to many people, but fundamentally it is a
compiler. Those are routinely implemented as command line tools, which
makes them easy to integrate into other software. I think a GUI would be
out of scope for the project – any GUI would effectively be a fully fledged
text editor. There are many projects that do provide some Pandoc user
interface, including the Stackedit web app, editor plugins, or
Rstudio/Knitr. The documentation links to various pandoc-related tools
under the entry “extras <https://github.com/jgm/pandoc/wiki/Pandoc-Extras>”.

I'm also not sure front end devs would be the main audience, as opposed to
academics?


On Tue, 21 May 2019 at 19:44, Aseem Prashar <prashara-e/prDBdGCFNcusGGlJDZ6w@public.gmane.org>
wrote:

> Hi everyone!
>
> Oregon State University's Free/Open Source Software class has us evaluate
> real-world open-source projects for inclusivity using a cognitive
> walk-through technique.
> I am opening this discussion thread to facilitate conversation on
> inclusivity within the Pandoc project.
>
> *Issue 1:* Our cognitive walk-through found that contributing to Pandoc
> page (https://github.com/jgm/pandoc/blob/master/CONTRIBUTING.md) doesn’t
> give enough information
> on how to set up the environment and start contributing to people who are
> new to open source to encourage them to contribute to this project.
>
> *Issue 2:* The documentation should also provide more instructions on
> setting up the test environment as most people contributing to open source
> for the first time will not be familiar with
> the testing methods used. The documentation on what kind of test is done
> and how to test new features should also be included.
>
> *Issue 3: *This tool is mainly for front end developers, but it has been
> implemented as a command line program, making a GUI for the tool will make
> using this tool easier and faster.
>
> Thank you for reading, looking forward to your responses.
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/7231afe1-fd0a-4e7d-93ce-fadb9030a244%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/7231afe1-fd0a-4e7d-93ce-fadb9030a244%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAJTYOd0Z8YcgVwRdPg_MM52RMaXq-FEJoSHqNPUZmtbpr%3Dj26g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 5385 bytes --]

Inclusivity Issues for new contributors

[Kolen Cheung]

[-- Attachment #1: Type: text/plain, Size: 2493 bytes --]

I also think your issue 3 mis-classify pandoc.

IMO an interface besides cli that is sorely needed is an easy to use API, not GUI. Certainly pandoc can be used as a Haskell library, but besides that probably not. Eg all existing Python interface are a wrapper of the cli which is “wrong”, eg a lot of performance penalty to call pandoc repeatedly.

While issue 1 or 2 might probably be true, the biggest barrier of getting involved is the language, Haskell. I think this is the biggest barrier of all and the 2 you mentioned is almost negligible comparing to this. Using myself as an example, I overcome issue 1 and 2 with relatively little effort. But I haven’t ever overcome the language barrier to be able to contribute to pandoc on non trivial tasks. And it is my regret that my “day job” doesn’t have room for the use of Haskell so that spending time mastering it is impossible for me.

So as long as pandoc is still written in Haskell, I think pandoc will not be “inclusive” for new contributors who likely don’t know Haskell beforehand (just by probability from such small community.)

However, note that (at least claimed by jgm) it would be impossible to accomplish what pandoc did if not written in Haskell. Also note that there’s independent parser to pandoc AST (sadly the only living one I know is closed source) which provides a subset of what pandoc does.

Also, ironically to solve the API problem I mentioned in the beginning, probably the best path towards it is first turing pandoc as a purely Haskell program (currently depends on Pearl’s regex, some C libraries such as YAML and libCommonMark, etc.) It is because if the program is Haskell only it allows it to be transpiled to eg Javascript. I personally would hope that it could be transpiled to C, or officially exposing a C FFI to be bind in other languages. (Libpandoc hasn’t been updated for 2 years.)

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/6b58c3f2-ba94-4f0d-8e3f-3c3bf4c71c73%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Inclusivity Issues for new contributors

[BPJ]

[-- Attachment #1: Type: text/plain, Size: 6686 bytes --]

(Sorry if I post this twice. Something "funny" happened at the first
attempt.)

Have you thought about that not everyone may prefer a GUI? Admittedly my
case is a bit special since I have a motor disability which makes using a
mouse hard for me while typing is reasonably easy, but there certainly are
people without any disabilities who prefer a CLI to a GUI. For one thing
Pandoc like many other CLI programs has a great many options, and in
Pandoc's case also the so-called extensions which in effect are additional
options which apply to input and/or output individually. Since extensions
were added later there admittedly are some options which ought to be
extensions, and in fact there are some features which perhaps ought to be
available as both options (applying to both input and output) and
extensions (applying to either input or output).

Allowing to set all these options through a GUI would mean a great many
check boxes, radio buttons and text boxes which might in fact be harder to
navigate and more deterrent than to read the manual, perhaps googling "how
to use a command line interface" and learning to use the CLI. In a GUI a
lot of options typically means a lot of dialogs and/or tabs which may be
hard to navigate: different options typically have to be grouped in
different dialogs or tabs and the grouping which appears best to one person
may be non-obvious or confusing to someone else. (One particular example is
the named styles manipulation dialog of LibreOffice, where language is set
on the Font tab and writing direction is set on the Alignment tab rather
than there being a Language and Script tab, with the result that users may
not — or at least not readily — find those options.) Explaining to someone
how to find their way in a maze of GUI dialogs and tabs can be very hard.
We also know that feature rich GUI programs like Word usually have many
features which most users never know about or find. In a CLI by contrast
all options are at least in principle equal citizens; you naturally learn
to use those options you need and when helping someone out you just need to
say "use the --foo or -f option" and perhaps provide a link to the online
manual. (I'm admittedly touting my own horn a bit here, since I contributed
the code which automatically inserts anchors and cross links for the
options in the Pandoc online manual.)

While there certainly are programs which support both a GUI and a CLI one
of them — most often the CLI — is then usually impoverished compared to the
other.  As others have said one of the beauties of a CLI program is that it
is reasonably easy to write wrappers, including GUI wrappers, for a typical
CLI program, and there already are Pandoc wrapper plugins for several text
editors.

Since probably everyone has a set or sets of options and extensions which
they use every time or repeatedly one thing which I *really* find missing
in Pandoc is the possibility to set options and extensions in one or more
configuration files, both a default one and special-purpose ones specified
in the CLI, in order to not having to type the same things every time. We
are many who have written wrappers to achieve this, and in fact wrappers
may be the preferable way to implement this, since different people may
prefer different configuration file formats. Makefiles may be the most
obvious workaround, not requiring any dedicated coding, but may be too
complicated and may also not be general enough. YAML is very powerful but
may be too powerful for some beginners — in particular its quoting rules
are often a stumbling block. For some an INI file format with sections for
different input and output formats may be preferable, while for still
others a simple text file containing options and extensions as you would
type them in the shell (possibly with the addition of line comments) may be
preferable. In fact the same users may prefer different formats for
different situations.

Den tis 21 maj 2019 19:45Aseem Prashar <prashara-e/prDBdGCFNcusGGlJDZ6w@public.gmane.org> skrev:

> Hi everyone!
>
> Oregon State University's Free/Open Source Software class has us evaluate
> real-world open-source projects for inclusivity using a cognitive
> walk-through technique.
> I am opening this discussion thread to facilitate conversation on
> inclusivity within the Pandoc project.
>
> *Issue 1:* Our cognitive walk-through found that contributing to Pandoc
> page (https://github.com/jgm/pandoc/blob/master/CONTRIBUTING.md) doesn’t
> give enough information
> on how to set up the environment and start contributing to people who are
> new to open source to encourage them to contribute to this project.
>
> *Issue 2:* The documentation should also provide more instructions on
> setting up the test environment as most people contributing to open source
> for the first time will not be familiar with
> the testing methods used. The documentation on what kind of test is done
> and how to test new features should also be included.
>
> *Issue 3: *This tool is mainly for front end developers, but it has been
> implemented as a command line program, making a GUI for the tool will make
> using this tool easier and faster.
>
> Thank you for reading, looking forward to your responses.
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/7231afe1-fd0a-4e7d-93ce-fadb9030a244%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/7231afe1-fd0a-4e7d-93ce-fadb9030a244%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhAHteunv14Ugkjw96wh4Z4WVDhhu4g3pJxk8Evbh8kaVQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 8082 bytes --]

Re: Inclusivity Issues for new contributors

[John MacFarlane]

It would not be hard at all to create a C binding
for pandoc that allowed you to do everything you can
do from the command line.

See
http://hackage.haskell.org/package/pandoc-2.7.2/docs/Text-Pandoc-App.html

The convertWithOpts function would be easy to wrap
in C, since the Opt structure has a FromJSON instance.
So a C function could be exported that took as input
a JSON-encoded specification of the options.

Exposing individual pandoc readers would also be
fairly easy; ReaderOptions is an instance of FromJSON,
and there's a JSON representation of the AST.

I see that WriterOptions is not an instance of
FromJSON.  I can't recall why, but it's likely because
writerSyntaxMap.  (Syntax in skylighting isn't an
instance of FromJSON.)  But this could easily be
fixed; it would be trivial to derive FromJSON for
the skylighting types.

Another thing we could fairly easily do is create a
pandoc-server program that keeps running and responds
to HTTP.

Kolen Cheung <christian.kolen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> I also think your issue 3 mis-classify pandoc.
>
> IMO an interface besides cli that is sorely needed is an easy to use API, not GUI. Certainly pandoc can be used as a Haskell library, but besides that probably not. Eg all existing Python interface are a wrapper of the cli which is “wrong”, eg a lot of performance penalty to call pandoc repeatedly.
>
> While issue 1 or 2 might probably be true, the biggest barrier of getting involved is the language, Haskell. I think this is the biggest barrier of all and the 2 you mentioned is almost negligible comparing to this. Using myself as an example, I overcome issue 1 and 2 with relatively little effort. But I haven’t ever overcome the language barrier to be able to contribute to pandoc on non trivial tasks. And it is my regret that my “day job” doesn’t have room for the use of Haskell so that spending time mastering it is impossible for me.
>
> So as long as pandoc is still written in Haskell, I think pandoc will not be “inclusive” for new contributors who likely don’t know Haskell beforehand (just by probability from such small community.)
>
> However, note that (at least claimed by jgm) it would be impossible to accomplish what pandoc did if not written in Haskell. Also note that there’s independent parser to pandoc AST (sadly the only living one I know is closed source) which provides a subset of what pandoc does.
>
> Also, ironically to solve the API problem I mentioned in the beginning, probably the best path towards it is first turing pandoc as a purely Haskell program (currently depends on Pearl’s regex, some C libraries such as YAML and libCommonMark, etc.) It is because if the program is Haskell only it allows it to be transpiled to eg Javascript. I personally would hope that it could be transpiled to C, or officially exposing a C FFI to be bind in other languages. (Libpandoc hasn’t been updated for 2 years.)
>
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/6b58c3f2-ba94-4f0d-8e3f-3c3bf4c71c73%40googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/yh480kef4qpht2.fsf%40johnmacfarlane.net.
For more options, visit https://groups.google.com/d/optout.

Re: Inclusivity Issues for new contributors

[mb21]

[-- Attachment #1.1: Type: text/plain, Size: 1954 bytes --]

If you want a GUI, have a look at https://panwriter.com


On Tuesday, May 21, 2019 at 7:44:54 PM UTC+2, Aseem Prashar wrote:
>
> Hi everyone!
>
> Oregon State University's Free/Open Source Software class has us evaluate 
> real-world open-source projects for inclusivity using a cognitive 
> walk-through technique.
> I am opening this discussion thread to facilitate conversation on 
> inclusivity within the Pandoc project. 
>
> *Issue 1:* Our cognitive walk-through found that contributing to Pandoc 
> page (https://github.com/jgm/pandoc/blob/master/CONTRIBUTING.md) doesn’t 
> give enough information
> on how to set up the environment and start contributing to people who are 
> new to open source to encourage them to contribute to this project.
>
> *Issue 2:* The documentation should also provide more instructions on 
> setting up the test environment as most people contributing to open source 
> for the first time will not be familiar with
> the testing methods used. The documentation on what kind of test is done 
> and how to test new features should also be included.
>
> *Issue 3: *This tool is mainly for front end developers, but it has been 
> implemented as a command line program, making a GUI for the tool will make 
> using this tool easier and faster.
>
> Thank you for reading, looking forward to your responses.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/69ca1d36-f27b-42d4-bf21-51e1fa6a528d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 3179 bytes --]

Re: Inclusivity Issues for new contributors

[CR]

[-- Attachment #1.1: Type: text/plain, Size: 710 bytes --]

I found a Pandoc GUI but it's from 2015, so it will be missing new Pandoc 
features. 
- PandocGUI. https://github.com/seeebiii/PandocGUI


-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/293da97d-6b02-4dff-85df-28671f39eb93%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 1179 bytes --]