[erlang-questions] Accessing the documentation at runtime

[Lutz Behnke]

Am 29.09.2016 um 15:49 schrieb Loïc Hoguin:
> On 09/29/2016 02:00 PM, Lutz Behnke wrote:
>>> *You should not have to run a server to read documentation!*
>>>
>>> Why would you open a socket to a local server (what port number btw?) to
>>> read a file that's *already on your filesystem*? Just open the file!
>>
>> Because having each file for each format on disk is a waste. If you only
>> ever want to use a single format, just prepare them for you. But don't
>> force me to use a format, just because you like it.
>
> But that's already the case. I only have man pages; I don't have HTML or
> PDF.
>
>> I don't where you see the difference between a server/filter that can do
>> it on the fly and some thin front-end that will prepare a complete doc
>> bundle in a desired format
>
> You are kidding?

No, I think I structured the sentence poorly. It should have been "a 
server/filter vs the filter plus a thin frontend for a-priory 
preparation". Where do you see the massive difference?
>
> Now Erlang needs to come with converters for every format people use.
> I'm advocating using a third party tool that handles all this mess
> automatically and produce the files along the release; up to you whether
> to install them or not.

I never said that the solution has to be written from scratch. Quite the 
contrary. Although there will have to be some adaption work to be done.

>
> My development system only has man pages; my CI servers don't have any
> documentation, as it should be.
>
>>> I'd understand if you'd use Vlad's suggestion of adding support for an
>>> existing doc server for integration into IDEs; but a custom server on
>>> top of a custom documentation format makes absolutely no sense.
>>>
>>> You are not going to solve documentation problems by writing more
>>> programs. You solve documentation problems by writing more or improving
>>> what's already there; and in the case of OTP by reducing the amount of
>>> custom code needed to maintain it.
>>>
>>> Documentation is hard enough. Keep it *simple*.
>>>
>> Yes, but there are different people can solve different issues, due to
>> different skill sets.
>>
>> Reading/groking documentation is hard too, so it makes no sense to take
>> people out of their comfort zone when using it. For me that zone is a
>> combination of firefox, ctrl-f and google. You like man, IIRC Joe likes
>> PDFs, Vlad wants integration into his IDE. Each to his own.
>
> Didn't say it couldn't be useful to integrate into IDEs. It's the rest
> that I have problems with. We don't need more custom code for building
> the documentation; we need less.
>


-- 
Lutz Behnke
Hochschule für Angewandte Wissenschaften Hamburg,
Labor für Allgemeine Informatik,

phone: +49 40 42875-8156    mailto:lutz.behnke@REDACTED
fax  : +49 40 2803770       http://users.informatik.haw-hamburg.de/~sage
Berliner Tor 7, 20099 Hamburg, Germany

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 5006 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160930/3ed7e953/attachment.bin>