10:29 p.m.
Hi,
Luxio seems to lack documentation. Shall I write some?
Are there any preferences on what it should be written in:
LDoc, LuaDoc, Sphinx?
Thanks,
Richard Ipsum
6:01 p.m.
On Sat, May 06, 2017 at 14:29:36 +0100, Richard Ipsum wrote:
Luxio seems to lack documentation. Shall I write some?
Are there any preferences on what it should be written in:
LDoc, LuaDoc, Sphinx?
Luxio does have a non-trivial amount of documentation, but it's not easy to
extract. There is an ldoc config file at the top level and so the right thing
to do would be to start from there and see what we can do to improve matters.
I have a tweaked ldoc C extractor somewhere which I can bring to bear to make
the code comments in luxio.c easier to grok when dealing with the source.
D.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
9:33 p.m.
New subject: [PATCH 0/2] luxio: Build and install documentation
repo: git://git.gitano.org.uk/personal/richardipsum/luxio.git
ref: richardipsum/build-ldoc
HEAD: 1a93f69b4f09a175a3dce8ddfa4e3864d401fbd1
Hi!
This builds and installs docs!
It is based on richardipsum/fix-default-goal, so that must be merged first!
Thanks!
Richard Ipsum
Richard Ipsum (2):
Makefile: Add rules to build and install docs
README: Add new optional step: install docs
Makefile | 14 +++++++++++++-
README | 13 +++++++------
2 files changed, 20 insertions(+), 7 deletions(-)
--
2.12.2.510.ge1104a5.dirty
9:33 p.m.
New subject: [PATCH 1/2] Makefile: Add rules to build and install docs
---
Makefile | 14 +++++++++++++-
1 file changed, 13 insertions(+), 1 deletion(-)
diff --git a/Makefile b/Makefile
index 4020cc9..3737d1e 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,7 @@
+PREFIX ?= /usr
+CP := cp -r
+RM := rm -rf
+
.PHONY: all
all: lua-5.1-try lua-5.2-try
@@ -6,6 +10,14 @@ include findlua.mk
.PHONY: install
install: lua-5.1-try-install lua-5.2-try-install
+.PHONY: install-doc
+install-doc: doc
+ $(INSTALL) -d $(DESTDIR)$(PREFIX)/share/doc/luxio
+ $(CP) doc/* $(DESTDIR)$(PREFIX)/share/doc/luxio
+
+doc:
+ ldoc .
+
CFLAGS ?= -O2 -Wall
INSTALL := /usr/bin/install
@@ -13,7 +25,7 @@ LUALIBS := $(patsubst %,luxio/%.lua, event simple subprocess)
.PHONY: clean
clean:
- $(RM) *.so *.o luxio_constants.inc luxio-5.1 luxio-5.2
+ $(RM) *.so *.o luxio_constants.inc luxio-5.1 luxio-5.2 doc
luxio_constants.inc: luxio_constants.inc.in const-proc.lua
$(LUA_REPL) ./const-proc.lua < $^ > $@
--
2.12.2.510.ge1104a5.dirty
11:56 p.m.
New subject: [PATCH 1/2] Makefile: Add rules to build and install docs
On Mon, May 08, 2017 at 15:30:02 +0100, Richard Ipsum wrote:
On Mon, May 08, 2017 at 01:33:30PM +0100, Richard Ipsum wrote:
[snip]
> ---
> +
> +doc:
> + ldoc .
> +
Bah, this rule should probably depend on luxio.c and luxio/simple.lua...
Probably on luxio/*.lua even if it's not pulling docs from all of them yet.
I don't mind if it's PHONY tbf, ldoc doesn't take long to run.
D.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
12:04 a.m.
New subject: [PATCH 1/2] Makefile: Add rules to build and install docs
On Mon, May 08, 2017 at 03:56:39PM +0100, Daniel Silverstone wrote:
On Mon, May 08, 2017 at 15:30:02 +0100, Richard Ipsum wrote:
> On Mon, May 08, 2017 at 01:33:30PM +0100, Richard Ipsum wrote:
> [snip]
> > ---
> > +
> > +doc:
> > + ldoc .
> > +
>
> Bah, this rule should probably depend on luxio.c and luxio/simple.lua...
Probably on luxio/*.lua even if it's not pulling docs from all of them yet.
I don't mind if it's PHONY tbf, ldoc doesn't take long to run.
Ack, I've no real preference wrt luxio/*.lua vs PHONY.
I'll send a v2 a bit later on.
9:33 p.m.
New subject: [PATCH 2/2] README: Add new optional step: install docs
---
README | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/README b/README
index b496d17..cd1aaa7 100644
--- a/README
+++ b/README
@@ -2,8 +2,8 @@ Luxio - Lightweight UNIX I/O and POSIX binding for Lua
------------------------------------------------------
Now:
- 0. Supports Lua 5.1 and Lua 5.2.
- 1. Reasonably good coverage of POSIX and BSD Sockets, including IPv6,
+ 0. Supports Lua 5.1 and Lua 5.2.
+ 1. Reasonably good coverage of POSIX and BSD Sockets, including IPv6,
and some GNU extensions.
2. Meant to be buildable anywhere that is POSIX.1-1996. If it's not,
there's a bug. These are likely, as I have nowhere other than
@@ -13,10 +13,10 @@ Now:
may return tables.
4. High-level wrapper library providing nice IO access and to misc.
utility functions. Generates useful errors in assert()able form,
- and provides meaningful __tostring metamethods to aid debugging.
+ and provides meaningful __tostring metamethods to aid debugging.
5. A high-level poll()-based event dispatch library.
6. Sub-process handling library (read/write io.popen with job control).
- 7. A prototype POSIX Message Queue-based IPC scheme that can serialise
+ 7. A prototype POSIX Message Queue-based IPC scheme that can serialise
most simple Lua values. (No closures, userdata, etc)
8. Liberal licence. (Same as Lua's. See the file LICENCE.)
@@ -24,9 +24,10 @@ Future:
0. Well-documented.
1. Well-tested.
2. Complete POSIX coverage (where appropriate).
- 3. Better socketing, specifically for datagram sockets.
- 4. Advanced features like file descriptor passing.
+ 3. Better socketing, specifically for datagram sockets.
+ 4. Advanced features like file descriptor passing.
How to build:
0. Type "make".
1. Optionally, type "make install".
+ 2. Optionally, type "make install-doc"
--
2.12.2.510.ge1104a5.dirty
7:44 a.m.
On Mon, May 08, 2017 at 10:01:49AM +0100, Daniel Silverstone wrote:
On Sat, May 06, 2017 at 14:29:36 +0100, Richard Ipsum wrote:
> Luxio seems to lack documentation. Shall I write some?
> Are there any preferences on what it should be written in:
> LDoc, LuaDoc, Sphinx?
Luxio does have a non-trivial amount of documentation, but it's not easy to
extract. There is an ldoc config file at the top level and so the right thing
to do would be to start from there and see what we can do to improve matters.
I have a tweaked ldoc C extractor somewhere which I can bring to bear to make
the code comments in luxio.c easier to grok when dealing with the source.
I've been fleshing out luxio documentation.[1]
So far I have the first 3 sections done, but it's quite a large task.
I think it'd be nice to have a comprehensive set of docs,
but if you'd rather we not do this for whatever reason I'd like
to know sooner rather than later! :D
Also would one commit for the entire document be okay or would you
prefer a series?
[1]:
https://git.gitano.org.uk/personal/richardipsum/luxio.git/tree/luxio.c?h=...
8:01 a.m.
New subject: [PATCH v2 0/2] luxio: Build and install documentation
repo: git://git.gitano.org.uk/personal/richardipsum/luxio.git
ref: richardipsum/build-ldoc-v2
HEAD: dde17e0715ddc4a4bb28fd1e842467a489a16341
% git diff richardipsum/build-ldoc richardipsum/build-ldoc-v2
diff --git a/Makefile b/Makefile
index 3737d1e..8d8d316 100644
--- a/Makefile
+++ b/Makefile
@@ -15,6 +15,7 @@ install-doc: doc
$(INSTALL) -d $(DESTDIR)$(PREFIX)/share/doc/luxio
$(CP) doc/* $(DESTDIR)$(PREFIX)/share/doc/luxio
+.PHONY: doc
doc:
ldoc .
Richard Ipsum (2):
Makefile: Add rules to build and install docs
README: Add new optional step: install docs
Makefile | 15 ++++++++++++++-
README | 13 +++++++------
2 files changed, 21 insertions(+), 7 deletions(-)
--
2.12.2.510.ge1104a5.dirty
8:01 a.m.
New subject: [PATCH 1/2] Makefile: Add rules to build and install docs
---
Makefile | 15 ++++++++++++++-
1 file changed, 14 insertions(+), 1 deletion(-)
diff --git a/Makefile b/Makefile
index 4020cc9..8d8d316 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,7 @@
+PREFIX ?= /usr
+CP := cp -r
+RM := rm -rf
+
.PHONY: all
all: lua-5.1-try lua-5.2-try
@@ -6,6 +10,15 @@ include findlua.mk
.PHONY: install
install: lua-5.1-try-install lua-5.2-try-install
+.PHONY: install-doc
+install-doc: doc
+ $(INSTALL) -d $(DESTDIR)$(PREFIX)/share/doc/luxio
+ $(CP) doc/* $(DESTDIR)$(PREFIX)/share/doc/luxio
+
+.PHONY: doc
+doc:
+ ldoc .
+
CFLAGS ?= -O2 -Wall
INSTALL := /usr/bin/install
@@ -13,7 +26,7 @@ LUALIBS := $(patsubst %,luxio/%.lua, event simple subprocess)
.PHONY: clean
clean:
- $(RM) *.so *.o luxio_constants.inc luxio-5.1 luxio-5.2
+ $(RM) *.so *.o luxio_constants.inc luxio-5.1 luxio-5.2 doc
luxio_constants.inc: luxio_constants.inc.in const-proc.lua
$(LUA_REPL) ./const-proc.lua < $^ > $@
--
2.12.2.510.ge1104a5.dirty
8:01 a.m.
New subject: [PATCH 2/2] README: Add new optional step: install docs
---
README | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/README b/README
index b496d17..cd1aaa7 100644
--- a/README
+++ b/README
@@ -2,8 +2,8 @@ Luxio - Lightweight UNIX I/O and POSIX binding for Lua
------------------------------------------------------
Now:
- 0. Supports Lua 5.1 and Lua 5.2.
- 1. Reasonably good coverage of POSIX and BSD Sockets, including IPv6,
+ 0. Supports Lua 5.1 and Lua 5.2.
+ 1. Reasonably good coverage of POSIX and BSD Sockets, including IPv6,
and some GNU extensions.
2. Meant to be buildable anywhere that is POSIX.1-1996. If it's not,
there's a bug. These are likely, as I have nowhere other than
@@ -13,10 +13,10 @@ Now:
may return tables.
4. High-level wrapper library providing nice IO access and to misc.
utility functions. Generates useful errors in assert()able form,
- and provides meaningful __tostring metamethods to aid debugging.
+ and provides meaningful __tostring metamethods to aid debugging.
5. A high-level poll()-based event dispatch library.
6. Sub-process handling library (read/write io.popen with job control).
- 7. A prototype POSIX Message Queue-based IPC scheme that can serialise
+ 7. A prototype POSIX Message Queue-based IPC scheme that can serialise
most simple Lua values. (No closures, userdata, etc)
8. Liberal licence. (Same as Lua's. See the file LICENCE.)
@@ -24,9 +24,10 @@ Future:
0. Well-documented.
1. Well-tested.
2. Complete POSIX coverage (where appropriate).
- 3. Better socketing, specifically for datagram sockets.
- 4. Advanced features like file descriptor passing.
+ 3. Better socketing, specifically for datagram sockets.
+ 4. Advanced features like file descriptor passing.
How to build:
0. Type "make".
1. Optionally, type "make install".
+ 2. Optionally, type "make install-doc"
--
2.12.2.510.ge1104a5.dirty
5:14 p.m.
New subject: [PATCH v2 0/2] luxio: Build and install documentation
On Tue, May 09, 2017 at 00:01:53 +0100, Richard Ipsum wrote:
repo: git://git.gitano.org.uk/personal/richardipsum/luxio.git
ref: richardipsum/build-ldoc-v2
HEAD: dde17e0715ddc4a4bb28fd1e842467a489a16341
Merged, thank you.
D.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
1913
days inactive
1920
days old
12 comments
2 participants
participants (2)
-
Daniel Silverstone -
Richard Ipsum