Use erl -man to provide help for erlang library functions

[Booker Bense]

I find myself switching a lot between 

iex> h foo 

and 

erl -man :foo 

What do people think about having the h function in IEX 

attempting to use erl -man to provide documentation? 

- Booker C. Bense 

[José Valim]

I think this is an idea worth exploring. People have been asking for mechanisms for showing Erlang documentation and I believe we should explore those. However, it must be system agnostic, so it should work well on Windows. That may rule man pages out but we may be able to retrieve the docs through other ways.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/8c8266de-51ce-4fbc-a7cf-0f2411a06206%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Booker Bense]

Well the other idea I had was using erlang dockets that Dash uses, but I'm not sure 

of the legalities of distributing that. 

- Booker C. Bense

[Booker Bense]

I have made a very rough start at 

     https://github.com/bbense/erlman

The idea is to find the erlang man pages directly and reformat the nroff as markdown. 

There are two tricky parts so far. 

1. Is there any way to get erlang to tell me what it is using for MANPATH in erl -man ? 

    On unix systems, I can probably figure it out by using :find_executable on erl. 

2. What exactly gets installed on a Windows Elixir install? Will the man pages be

     there or will we need to prompt the user to install them? What will the filename

     of the man pages be? (i.e. what is the argument to File.read! on Windows. )

thanks, 

- Booker C. Bense 

On Monday, May 25, 2015 at 12:56:07 AM UTC-7, José Valim wrote:

[José Valim]

That's nice, I thought the conversion to markdown would be more complex.

It is also worth pointed out that the Erlang documentation is written as XML. Traversing the XML may be a better idea because we would also be able to get documentation per function too, in a more structured format, and it should work on Windows.

Although I am not sure how much more complex it would get.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/ecb11d3b-3f5d-4f94-a673-df681c383811%40googlegroups.com.

[Booker Bense]

I guess it comes down to how to manage the external dependencies. The XML doc files will have

to be either downloaded or included in elixir and then you run into version problems. 

There is also the problem of parsing the xml with standard libraries, but it seems like :xmerl should 

be workable. 

Since the man files are written by transform from xml, it should be possible to reverse engineer the signature. 

i.e. Sequence a,b,c of nroff macro corresponds to <func> in the original XML. 

That only works as  long as the nroff stuff never gets tweaked ( a fair assumption at this point I think). 

I guess I will have to break down and see if I can install Elixir on a windows box somewhere. 

- Booker C. Bense  

--
You received this message because you are subscribed to a topic in the Google Groups "elixir-lang-core" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/elixir-lang-core/nnyBdZ22hqk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JK39PCJQjm%3D4oXRN5aXYoF%2BBQgLuD41pHO1DRSxeyVww%40mail.gmail.com.

[Booker Bense]

I'm fairly close to having code that can provide a reasonable emulation of Code.get_docs for erlang functions

using the man pages. 

I did investigate what gets installed with the standard windows install of erlang and it only gets the html versions

of the man pages. 

This is what I'm thinking about going forward. 

Limitations:

Provide a solution that only works with what is already installed. (i.e. only use the documentation

and libraries that are already installed. )

Parsing html is without the support of a standard library is too complex. 

A simple library that can parse erlang nroff is not too complex. 

The solution has to work on both Windows and Unix platforms. 

Solution: 

If man pages are available use them to provide documentation via printing to the console in

iex. 

If only html pages are available, use an os command to have them displayed in the browser.

(i.e. on a mac run "open foo.html", xdg-open on linux,  on windows ( cmd /c start foo.html ) ) 

- Booker C. Bense 

[Booker Bense]

On Thursday, June 4, 2015 at 4:36:35 PM UTC-7, Booker Bense wrote:

I'm fairly close to having code that can provide a reasonable emulation of Code.get_docs for erlang functions

using the man pages. 

Elrman.h is working at the moment. I did cheat a lot in converting the nroff to markdown. It doesn't really 

implement the nroff state machine. But at least on my machine the results are readable. I suspect there is 

a point of diminishing returns in attempting to reverse engineer the nroff and some pages will just not work

since they don't follow the format. 

iex(2)> Erlman.h(":binary.split")

                               def :binary.split

split(Subject, Pattern) -> Parts

Types:

Subject = binary()

Pattern = binary() | [binary()] | cp()

Parts = [binary()]

The same as split(Subject, Pattern, []).

                               def :binary.split

split(Subject, Pattern, Options) -> Parts

Types:

Subject = binary()

Pattern = binary() | [binary()] | cp()

Options = [Option]

Option = {scope, part()} | trim | global

Parts = [binary()]

Splits Subject into a list of binaries based on Pattern. If the option global

is not given, only the first occurrence of Pattern in Subject will give rise to

a split. The parts of Pattern actually found in Subject are not included in the

result. Example:

1> binary:split(<<1,255,4,0,0,0,2,3>>, [<<0,0,0>>,<<2>>],[]). [<<1,255,4>>,

<<2,3>>] 2> binary:split(<<0,1,0,0,4,255,255,9>>, [<<0,0>>,

<<255,255>>],[global]). [<<0,1>>,<<4>>,<<9>>]

Summary of options: 2

[:ok, :ok]

iex(3)> Erlman.h(":binary")

                                    :binary

BINARY 3 "STDLIB 2.4" "ERICSSON AB" "ERLANG MODULE DEFINITION"

NAME

binary - Library for handling binary data

DESCRIPTION

This module contains functions for manipulating byte-oriented binaries.

Although the majority of functions could be implemented using bit-syntax, the

functions in this library are highly optimized and are expected to either

execute faster or consume less memory (or both) than a counterpart written in

pure Erlang. The module is implemented according to the EEP (Erlang Enhancement

Proposal) 31.

Note: The library handles byte-oriented data. Bitstrings that are not binaries

(does not contain whole octets of bits) will result in a badarg exception being

thrown from any of the functions in this module.

DATA TYPES

cp()

Opaque data-type representing a compiled search-pattern. Guaranteed to be a

tuple() to allow programs to distinguish it from non precompiled search

patterns.

part() = {Start :: integer() >= 0, Length :: integer()}

A representaion of a part (or range) in a binary. Start is a zero-based offset

into a binary() and Length is the length of that part. As input to functions in

this module, a reverse part specification is allowed, constructed with a

negative Length, so that the part of the binary begins at Start + Length and is

-Length long. This is useful for referencing the last N bytes of a binary as

{size(Binary), -N}. The functions in this module always return part()'s with

positive Length.

:ok 

[José Valim]

That's awesome Booker. Do you have the code hosted somewhere? It would be nice to have an idea of the complexity. It would also help a proof of concept on the XML versions to see which one ends up being less complex. :)

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/1a549dd4-ffc7-4798-a736-e6e1283471c7%40googlegroups.com.

[Booker Bense]

It's at 

https://github.com/bbense/erlman

It still needs a lot of work,( tests and cleanup) I just wanted to see how far I could get. 

- Booker C. Bense

--
You received this message because you are subscribed to a topic in the Google Groups "elixir-lang-core" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/elixir-lang-core/nnyBdZ22hqk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4KS1-TuPp_VeHEsoOobO%2B%3DNmkFcMnRSRs_Jd7Pv8oc60A%40mail.gmail.com.